<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.		-*-Text-*- -->

<div class='chapter' id='11'>11. Strings</div><p class='cindent'><!-- string -->
	Strings are a type of array which are constants (they self-evaluate)
and have as their printed representation a sequence of characters enclosed
in quote marks, for example <!-- open: 1, close: 0 --><font class="lisp">"foo bar"</font><!-- open: 1, close: 1 --> <!-- MATCHED MATCHED MATCHED -->.  Strings are the right data type
to use for text-processing.
	The functions described in this section provide a variety of
useful operations on strings.  Several of the functions actually work
on any type of 1-dimensional array and may be useful for other than string processing.
<!-- open: 2, close: 1 --><font class="lisp">art-16b</font><!-- open: 2, close: 2 --> <!-- MATCHED MATCHED MATCHED --> arrays (arrays of 16-bit positive numbers) are often used
as strings; the extra bits allow for an expanded character set.
	In place of a string, most of these functions will accept a symbol or a fixnum
as an argument, and will coerce it into a string.  Given a symbol, its print name,
which is a string, will be used.  Given a fixnum, a 1 character long string
containing the character designated by that fixnum will be used.
	Note that the length of a string is computed using <!-- open: 3, close: 2 --><font class="lisp">array-active-length</font><!-- open: 3, close: 3 --> <!-- MATCHED MATCHED MATCHED -->,
so that if a string has an array-leader, element 0 of the leader (called the
<!-- open: 4, close: 3 --><font class="italic">fill pointer</font><!-- open: 4, close: 4 --> <!-- MATCHED MATCHED MATCHED -->) will be taken as the length.

	Since strings are arrays, the usual array-referencing function <!-- open: 5, close: 4 --><font class="lisp">aref</font><!-- open: 5, close: 5 --> <!-- MATCHED MATCHED MATCHED -->
is used to extract the characters of the string as fixnums.  For example,
<pre class='lisp'>
(aref "frob" 1) =&gt; 162  <!-- open: 6, close: 5 --><font class="main">;lower-case r</font><!-- open: 6, close: 6 --> <!-- MATCHED MATCHED MATCHED -->
</pre>
It is also legal to store into strings (using <!-- open: 7, close: 6 --><font class="lisp">aset</font><!-- open: 7, close: 7 --> <!-- MATCHED MATCHED MATCHED -->).
As with <!-- open: 8, close: 7 --><font class="lisp">rplaca</font><!-- open: 8, close: 8 --> <!-- MATCHED MATCHED MATCHED --> on lists, this changes the actual object; one must be careful
to understand where side-effects will propagate to.

<div class='section' id='11.1'>11.1 String Manipulation</div>
<div class='defun' id='character'>
  <font class='exdent'>
    <font class='funcname'>character </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
	<!-- open: 9, close: 8 --><font class="lisp">character</font><!-- open: 9, close: 9 --> <!-- MATCHED MATCHED MATCHED --> coerces <!-- open: 10, close: 9 --><font class="italic">x</font><!-- open: 10, close: 10 --> <!-- MATCHED MATCHED MATCHED --> to a single character,
represented as a fixnum.  If <!-- open: 11, close: 10 --><font class="italic">x</font><!-- open: 11, close: 11 --> <!-- MATCHED MATCHED MATCHED --> is a number, it is returned.  If
<!-- open: 12, close: 11 --><font class="italic">x</font><!-- open: 12, close: 12 --> <!-- MATCHED MATCHED MATCHED --> is a string or an array, its first element is returned.  If
<!-- open: 13, close: 12 --><font class="italic">x</font><!-- open: 13, close: 13 --> <!-- MATCHED MATCHED MATCHED --> is a symbol, the first character of its pname is returned.
Otherwise, an error occurs.
</div>

<div class='defun' id='char-equal'>
  <font class='exdent'>
    <font class='funcname'>char-equal </font>
    <font class='italic' color='purple'>ch1 ch2</font>
  </font><br>
	This is the primitive for comparing characters for equality;
many of the string functions call it.  <!-- open: 14, close: 13 --><font class="italic">ch1</font><!-- open: 14, close: 14 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 15, close: 14 --><font class="italic">ch2</font><!-- open: 15, close: 15 --> <!-- MATCHED MATCHED MATCHED -->
must be fixnums.  The result is <!-- open: 16, close: 15 --><font class="lisp">t</font><!-- open: 16, close: 16 --> <!-- MATCHED MATCHED MATCHED --> if the characters are equal ignoring
case and font, otherwise <!-- open: 17, close: 16 --><font class="lisp">nil</font><!-- open: 17, close: 17 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 18, close: 17 --><font class="lisp">%%ch-char</font><!-- open: 18, close: 18 --> <!-- MATCHED MATCHED MATCHED --> is the byte-specifier for the portion of a character
which excludes the font information.
</div>

<div class='defun' id='char-lessp'>
  <font class='exdent'>
    <font class='funcname'>char-lessp </font>
    <font class='italic' color='purple'>ch1 ch2</font>
  </font><br>
	This is the primitive for comparing characters for order;
many of the string functions call it.  <!-- open: 19, close: 18 --><font class="italic">ch1</font><!-- open: 19, close: 19 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 20, close: 19 --><font class="italic">ch2</font><!-- open: 20, close: 20 --> <!-- MATCHED MATCHED MATCHED -->
must be fixnums.  The result is <!-- open: 21, close: 20 --><font class="lisp">t</font><!-- open: 21, close: 21 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 22, close: 21 --><font class="italic">ch1</font><!-- open: 22, close: 22 --> <!-- MATCHED MATCHED MATCHED --> comes before <!-- open: 23, close: 22 --><font class="italic">ch2</font><!-- open: 23, close: 23 --> <!-- MATCHED MATCHED MATCHED -->
ignoring case and font, otherwise <!-- open: 24, close: 23 --><font class="lisp">nil</font><!-- open: 24, close: 24 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defvar' id='alphabetic-case-affects-string-comparison'><font class='exdent'><font class='funcname' id='alphabetic-case-affects-string-comparison'>alphabetic-case-affects-string-comparison</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->This variable is normally <!-- open: 25, close: 24 --><font class="lisp">nil</font><!-- open: 25, close: 25 --> <!-- MATCHED MATCHED MATCHED -->.  If it is <!-- open: 26, close: 25 --><font class="lisp">t</font><!-- open: 26, close: 26 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 27, close: 26 --><font class="lisp">char-equal</font><!-- open: 27, close: 27 --> <!-- MATCHED MATCHED MATCHED -->,
<!-- open: 28, close: 27 --><font class="lisp">char-lessp</font><!-- open: 28, close: 28 --> <!-- MATCHED MATCHED MATCHED -->, and the string searching and comparison functions will
distinguish between upper-case and lower-case letters.  It is alright
to bind this to <!-- open: 29, close: 28 --><font class="lisp">t</font><!-- open: 29, close: 29 --> <!-- MATCHED MATCHED MATCHED -->, but changing its global value to <!-- open: 30, close: 29 --><font class="lisp">t</font><!-- open: 30, close: 30 --> <!-- MATCHED MATCHED MATCHED --> will
break many system functions and user interfaces and so is not recommended.
</div>

<div class='defun' id='string'>
  <font class='exdent'>
    <font class='funcname'>string </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
	<!-- open: 31, close: 30 --><font class="lisp">string</font><!-- open: 31, close: 31 --> <!-- MATCHED MATCHED MATCHED --> coerces <!-- open: 32, close: 31 --><font class="italic">x</font><!-- open: 32, close: 32 --> <!-- MATCHED MATCHED MATCHED --> into a string.  Most of the string
functions apply this to their string arguments.
If <!-- open: 33, close: 32 --><font class="italic">x</font><!-- open: 33, close: 33 --> <!-- MATCHED MATCHED MATCHED --> is a string or an array, it is returned.  If <!-- open: 34, close: 33 --><font class="italic">x</font><!-- open: 34, close: 34 --> <!-- MATCHED MATCHED MATCHED --> is
a symbol, its pname is returned.  If <!-- open: 35, close: 34 --><font class="italic">x</font><!-- open: 35, close: 35 --> <!-- MATCHED MATCHED MATCHED --> is a number, a 1-character
long string containing it is returned.  Otherwise, an error occurs.
</div>

<div class='defun' id='string-length'>
  <font class='exdent'>
    <font class='funcname'>string-length </font>
    <font class='italic' color='purple'>string</font>
  </font><br>
	<!-- open: 36, close: 35 --><font class="lisp">string-length</font><!-- open: 36, close: 36 --> <!-- MATCHED MATCHED MATCHED --> returns the number of characters in <!-- open: 37, close: 36 --><font class="italic">string</font><!-- open: 37, close: 37 --> <!-- MATCHED MATCHED MATCHED -->.  This is 1
if <!-- open: 38, close: 37 --><font class="italic">string</font><!-- open: 38, close: 38 --> <!-- MATCHED MATCHED MATCHED --> is a number, the <!-- open: 39, close: 38 --><font class="lisp">array-active-length</font><!-- open: 39, close: 39 --> <!-- MATCHED MATCHED MATCHED -->
(see <font color='red'>LINK:(</font>array-active-length-fun))
if <!-- open: 40, close: 39 --><font class="italic">string</font><!-- open: 40, close: 40 --> <!-- MATCHED MATCHED MATCHED -->
is an array, or the <!-- open: 41, close: 40 --><font class="lisp">array-active-length</font><!-- open: 41, close: 41 --> <!-- MATCHED MATCHED MATCHED --> of the pname if <!-- open: 42, close: 41 --><font class="italic">string</font><!-- open: 42, close: 42 --> <!-- MATCHED MATCHED MATCHED --> is a symbol.
</div>

<div class='defun' id='string-equal'>
  <font class='exdent'>
    <font class='funcname'>string-equal </font>
    <font class='italic' color='purple'>string1 string2 &optional (idx1 0) (idx2 0) lim1 lim2</font>
  </font><br>
	<!-- open: 43, close: 42 --><font class="lisp">string-equal</font><!-- open: 43, close: 43 --> <!-- MATCHED MATCHED MATCHED --> compares two strings, returning <!-- open: 44, close: 43 --><font class="lisp">t</font><!-- open: 44, close: 44 --> <!-- MATCHED MATCHED MATCHED --> if
they are equal and <!-- open: 45, close: 44 --><font class="lisp">nil</font><!-- open: 45, close: 45 --> <!-- MATCHED MATCHED MATCHED --> if they are not.  The comparison ignores
the extra "font" bits in 16-bit strings
and ignores alphabetic case.  <!-- open: 46, close: 45 --><font class="lisp">equal</font><!-- open: 46, close: 46 --> <!-- MATCHED MATCHED MATCHED --> calls <!-- open: 47, close: 46 --><font class="lisp">string-equal</font><!-- open: 47, close: 47 --> <!-- MATCHED MATCHED MATCHED --> if
applied to two strings.
	The optional arguments <!-- open: 48, close: 47 --><font class="italic">idx1</font><!-- open: 48, close: 48 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 49, close: 48 --><font class="italic">idx2</font><!-- open: 49, close: 49 --> <!-- MATCHED MATCHED MATCHED --> are the starting
indices into the strings.  The optional arguments <!-- open: 50, close: 49 --><font class="italic">lim1</font><!-- open: 50, close: 50 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 51, close: 50 --><font class="italic">lim2</font><!-- open: 51, close: 51 --> <!-- MATCHED MATCHED MATCHED -->
are the final indices; the comparison stops just <!-- open: 52, close: 51 --><font class="italic">before</font><!-- open: 52, close: 52 --> <!-- MATCHED MATCHED MATCHED --> the final index.
<!-- open: 53, close: 52 --><font class="italic">lim1</font><!-- open: 53, close: 53 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 54, close: 53 --><font class="italic">lim2</font><!-- open: 54, close: 54 --> <!-- MATCHED MATCHED MATCHED --> default to the lengths of the strings.  These arguments are provided
so that you can efficiently compare substrings.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(string-equal "Foo" "foo") =&gt; t
(string-equal "foo" "bar") =&gt; nil
(string-equal "element" "select" 0 1 3 4) =&gt; t
</pre>
</div>

<div class='defun' id='%string-equal'>
  <font class='exdent'>
    <font class='funcname'>%string-equal </font>
    <font class='italic' color='purple'>string1 idx1 string2 idx2 count</font>
  </font><br>
<!-- open: 55, close: 54 --><font class="lisp">%string-equal</font><!-- open: 55, close: 55 --> <!-- MATCHED MATCHED MATCHED --> is the microcode primitive which <!-- open: 56, close: 55 --><font class="lisp">string-equal</font><!-- open: 56, close: 56 --> <!-- MATCHED MATCHED MATCHED --> calls.
It returns <!-- open: 57, close: 56 --><font class="lisp">t</font><!-- open: 57, close: 57 --> <!-- MATCHED MATCHED MATCHED --> if the <!-- open: 58, close: 57 --><font class="italic">count</font><!-- open: 58, close: 58 --> <!-- MATCHED MATCHED MATCHED --> characters of <!-- open: 59, close: 58 --><font class="italic">string1</font><!-- open: 59, close: 59 --> <!-- MATCHED MATCHED MATCHED --> starting
at <!-- open: 60, close: 59 --><font class="italic">idx1</font><!-- open: 60, close: 60 --> <!-- MATCHED MATCHED MATCHED --> are <!-- open: 61, close: 60 --><font class="lisp">char-equal</font><!-- open: 61, close: 61 --> <!-- MATCHED MATCHED MATCHED --> to the <!-- open: 62, close: 61 --><font class="italic">count</font><!-- open: 62, close: 62 --> <!-- MATCHED MATCHED MATCHED --> characters of <!-- open: 63, close: 62 --><font class="italic">string2</font><!-- open: 63, close: 63 --> <!-- MATCHED MATCHED MATCHED -->
starting at <!-- open: 64, close: 63 --><font class="italic">idx2</font><!-- open: 64, close: 64 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 65, close: 64 --><font class="lisp">nil</font><!-- open: 65, close: 65 --> <!-- MATCHED MATCHED MATCHED --> if the characters are not equal or
if <!-- open: 66, close: 65 --><font class="italic">count</font><!-- open: 66, close: 66 --> <!-- MATCHED MATCHED MATCHED --> runs off the length of either array.

Instead of a fixnum, <!-- open: 67, close: 66 --><font class="italic">count</font><!-- open: 67, close: 67 --> <!-- MATCHED MATCHED MATCHED --> may also be <!-- open: 68, close: 67 --><font class="lisp">nil</font><!-- open: 68, close: 68 --> <!-- MATCHED MATCHED MATCHED -->.  In this case,
<!-- open: 69, close: 68 --><font class="lisp">%string-equal</font><!-- open: 69, close: 69 --> <!-- MATCHED MATCHED MATCHED --> compares
the substring from <!-- open: 70, close: 69 --><font class="italic">idx1</font><!-- open: 70, close: 70 --> <!-- MATCHED MATCHED MATCHED --> to <!-- open: 71, close: 70 --><font class="lisp">(string-length <!-- open: 72, close: 70 --><font class="italic">string1</font><!-- open: 72, close: 71 -->)</font><!-- open: 72, close: 72 --> <!-- MATCHED MATCHED MATCHED -->
against the substring from <!-- open: 73, close: 72 --><font class="italic">idx2</font><!-- open: 73, close: 73 --> <!-- MATCHED MATCHED MATCHED --> to <!-- open: 74, close: 73 --><font class="lisp">(string-length <!-- open: 75, close: 73 --><font class="italic">string2</font><!-- open: 75, close: 74 -->)</font><!-- open: 75, close: 75 --> <!-- MATCHED MATCHED MATCHED -->.
If the lengths of these substrings differ, then they are not equal and
<!-- open: 76, close: 75 --><font class="lisp">nil</font><!-- open: 76, close: 76 --> <!-- MATCHED MATCHED MATCHED --> is returned.

<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent --><!-- open: 77, close: 76 --><font class="main">To compare the two strings <!-- open: 78, close: 76 --><font class="italic">foo</font><!-- open: 78, close: 77 --> and <!-- open: 79, close: 77 --><font class="italic">bar</font><!-- open: 79, close: 78 -->:</font><!-- open: 79, close: 79 --> <!-- MATCHED MATCHED MATCHED -->
(%string-equal <!-- open: 80, close: 79 --><font class="italic">foo</font><!-- open: 80, close: 80 --> <!-- MATCHED MATCHED MATCHED --> 0 <!-- open: 81, close: 80 --><font class="italic">bar</font><!-- open: 81, close: 81 --> <!-- MATCHED MATCHED MATCHED --> nil)
<!-- open: 82, close: 81 --><font class="main">To see if the string <!-- open: 83, close: 81 --><font class="italic">foo</font><!-- open: 83, close: 82 --> starts with the characters <!-- open: 84, close: 82 --><font class="lisp">"bar"</font><!-- open: 84, close: 83 -->:</font><!-- open: 84, close: 84 --> <!-- MATCHED MATCHED MATCHED -->
(%string-equal <!-- open: 85, close: 84 --><font class="italic">foo</font><!-- open: 85, close: 85 --> <!-- MATCHED MATCHED MATCHED --> 0 "bar" 0 3)
</pre>
</div>

<div class='defun' id='string-lessp'>
  <font class='exdent'>
    <font class='funcname'>string-lessp </font>
    <font class='italic' color='purple'>string1 string2</font>
  </font><br>
	<!-- open: 86, close: 85 --><font class="lisp">string-lessp</font><!-- open: 86, close: 86 --> <!-- MATCHED MATCHED MATCHED --> compares two strings using dictionary order.
The result is <!-- open: 87, close: 86 --><font class="lisp">t</font><!-- open: 87, close: 87 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 88, close: 87 --><font class="italic">string1</font><!-- open: 88, close: 88 --> <!-- MATCHED MATCHED MATCHED --> is the lesser, and <!-- open: 89, close: 88 --><font class="lisp">nil</font><!-- open: 89, close: 89 --> <!-- MATCHED MATCHED MATCHED -->
if they are equal or <!-- open: 90, close: 89 --><font class="italic">string2</font><!-- open: 90, close: 90 --> <!-- MATCHED MATCHED MATCHED --> is the lesser.
</div>

<div class='defun' id='substring'>
  <font class='exdent'>
    <font class='funcname'>substring </font>
    <font class='italic' color='purple'>string start &optional end area</font>
  </font><br>
	This extracts a substring of <!-- open: 91, close: 90 --><font class="italic">string</font><!-- open: 91, close: 91 --> <!-- MATCHED MATCHED MATCHED -->, starting at the
character specified by <!-- open: 92, close: 91 --><font class="italic">start</font><!-- open: 92, close: 92 --> <!-- MATCHED MATCHED MATCHED --> and going up to but not including
the character specified by <!-- open: 93, close: 92 --><font class="italic">end</font><!-- open: 93, close: 93 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 94, close: 93 --><font class="italic">start</font><!-- open: 94, close: 94 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 95, close: 94 --><font class="italic">end</font><!-- open: 95, close: 95 --> <!-- MATCHED MATCHED MATCHED --> are
0-origin indices.  The length of the returned string is <!-- open: 96, close: 95 --><font class="italic">end</font><!-- open: 96, close: 96 --> <!-- MATCHED MATCHED MATCHED --> minus
<!-- open: 97, close: 96 --><font class="italic">start</font><!-- open: 97, close: 97 --> <!-- MATCHED MATCHED MATCHED -->.  If <!-- open: 98, close: 97 --><font class="italic">end</font><!-- open: 98, close: 98 --> <!-- MATCHED MATCHED MATCHED --> is not specified it defaults to the length
of <!-- open: 99, close: 98 --><font class="italic">string</font><!-- open: 99, close: 99 --> <!-- MATCHED MATCHED MATCHED -->.  The area in which the result is to be consed may be
optionally specified.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(substring "Nebuchadnezzar" 4 8) =&gt; "chad"
</pre>
</div>

<div class='defun' id='nsubstring'>
  <font class='exdent'>
    <font class='funcname'>nsubstring </font>
    <font class='italic' color='purple'>string start &optional end area</font>
  </font><br>
<!-- open: 100, close: 99 --><font class="lisp">nsubstring</font><!-- open: 100, close: 100 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 101, close: 100 --><font class="lisp">substring</font><!-- open: 101, close: 101 --> <!-- MATCHED MATCHED MATCHED --> except that the substring
is not copied; instead an indirect array (see <a href='fd_arr.html#indirect-array'>this link</a>) is created which shares part
of the argument <!-- open: 102, close: 101 --><font class="italic">string</font><!-- open: 102, close: 102 --> <!-- MATCHED MATCHED MATCHED -->.  Modifying one string will modify the other.

Note that <!-- open: 103, close: 102 --><font class="lisp">nsubstring</font><!-- open: 103, close: 103 --> <!-- MATCHED MATCHED MATCHED --> does not necessarily use less storage than
<!-- open: 104, close: 103 --><font class="lisp">substring</font><!-- open: 104, close: 104 --> <!-- MATCHED MATCHED MATCHED -->; an <!-- open: 105, close: 104 --><font class="lisp">nsubstring</font><!-- open: 105, close: 105 --> <!-- MATCHED MATCHED MATCHED --> of any length uses the same amount of
storage as a <!-- open: 106, close: 105 --><font class="lisp">substring</font><!-- open: 106, close: 106 --> <!-- MATCHED MATCHED MATCHED --> 12 characters long.
</div>

<div class='defun' id='string-append'>
  <font class='exdent'>
    <font class='funcname'>string-append </font>
    <font class='italic' color='purple'>&rest strings</font>
  </font><br>
Any number of strings are copied and concatenated into a single string.
With a single argument, <!-- open: 107, close: 106 --><font class="lisp">string-append</font><!-- open: 107, close: 107 --> <!-- MATCHED MATCHED MATCHED --> simply copies it.
If the first argument is an array, the result will be an array of the same type.
Thus <!-- open: 108, close: 107 --><font class="lisp">string-append</font><!-- open: 108, close: 108 --> <!-- MATCHED MATCHED MATCHED --> can be
used to copy and concatenate any type of 1-dimensional array.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-append 41 "foo" 41) =&gt; "!foo!"
</pre>
</div>

<div class='defun' id='string-trim'>
  <font class='exdent'>
    <font class='funcname'>string-trim </font>
    <font class='italic' color='purple'>char-list string</font>
  </font><br>
	This returns a <!-- open: 109, close: 108 --><font class="lisp">substring</font><!-- open: 109, close: 109 --> <!-- MATCHED MATCHED MATCHED --> of <!-- open: 110, close: 109 --><font class="italic">string</font><!-- open: 110, close: 110 --> <!-- MATCHED MATCHED MATCHED -->, with all characters
in <!-- open: 111, close: 110 --><font class="italic">char-list</font><!-- open: 111, close: 111 --> <!-- MATCHED MATCHED MATCHED --> stripped off of the beginning and end.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-trim '(40) "  Dr. No  ") =&gt; "Dr. No"
</pre>
</div>

<div class='defun' id='string-left-trim'>
  <font class='exdent'>
    <font class='funcname'>string-left-trim </font>
    <font class='italic' color='purple'>char-list string</font>
  </font><br>
	This returns a <!-- open: 112, close: 111 --><font class="lisp">substring</font><!-- open: 112, close: 112 --> <!-- MATCHED MATCHED MATCHED --> of <!-- open: 113, close: 112 --><font class="italic">string</font><!-- open: 113, close: 113 --> <!-- MATCHED MATCHED MATCHED -->, with all characters
in <!-- open: 114, close: 113 --><font class="italic">char-list</font><!-- open: 114, close: 114 --> <!-- MATCHED MATCHED MATCHED --> stripped off of the beginning.
</div>

<div class='defun' id='string-right-trim'>
  <font class='exdent'>
    <font class='funcname'>string-right-trim </font>
    <font class='italic' color='purple'>char-list string</font>
  </font><br>
	This returns a <!-- open: 115, close: 114 --><font class="lisp">substring</font><!-- open: 115, close: 115 --> <!-- MATCHED MATCHED MATCHED --> of <!-- open: 116, close: 115 --><font class="italic">string</font><!-- open: 116, close: 116 --> <!-- MATCHED MATCHED MATCHED -->, with all characters
in <!-- open: 117, close: 116 --><font class="italic">char-list</font><!-- open: 117, close: 117 --> <!-- MATCHED MATCHED MATCHED --> stripped off of the end.
</div>

<div class='defun' id='char-upcase'>
  <font class='exdent'>
    <font class='funcname'>char-upcase </font>
    <font class='italic' color='purple'>ch</font>
  </font><br>
	If <!-- open: 118, close: 117 --><font class="italic">ch</font><!-- open: 118, close: 118 --> <!-- MATCHED MATCHED MATCHED -->, which must be a fixnum, is a lower-case alphabetic
character its upper-case form is returned; otherwise, <!-- open: 119, close: 118 --><font class="italic">ch</font><!-- open: 119, close: 119 --> <!-- MATCHED MATCHED MATCHED --> itself is
returned.  If font information is present it is preserved.
</div>

<div class='defun' id='char-downcase'>
  <font class='exdent'>
    <font class='funcname'>char-downcase </font>
    <font class='italic' color='purple'>ch</font>
  </font><br>
	If <!-- open: 120, close: 119 --><font class="italic">ch</font><!-- open: 120, close: 120 --> <!-- MATCHED MATCHED MATCHED -->, which must be a fixnum, is a upper-case alphabetic
character its lower-case form is returned; otherwise, <!-- open: 121, close: 120 --><font class="italic">ch</font><!-- open: 121, close: 121 --> <!-- MATCHED MATCHED MATCHED --> itself is
returned.  If font information is present it is preserved.
</div>

<div class='defun' id='string-upcase'>
  <font class='exdent'>
    <font class='funcname'>string-upcase </font>
    <font class='italic' color='purple'>string</font>
  </font><br>
	Returns a copy of <!-- open: 122, close: 121 --><font class="italic">string</font><!-- open: 122, close: 122 --> <!-- MATCHED MATCHED MATCHED -->, with all lower case alphabetic
characters replaced by the corresponding upper case characters.
</div>

<div class='defun' id='string-downcase'>
  <font class='exdent'>
    <font class='funcname'>string-downcase </font>
    <font class='italic' color='purple'>string</font>
  </font><br>
	Returns a copy of <!-- open: 123, close: 122 --><font class="italic">string</font><!-- open: 123, close: 123 --> <!-- MATCHED MATCHED MATCHED -->, with all upper case alphabetic
characters replaced by the corresponding lower case characters.
</div>

<div class='defun' id='string-reverse'>
  <font class='exdent'>
    <font class='funcname'>string-reverse </font>
    <font class='italic' color='purple'>string</font>
  </font><br>
	Returns a copy of <!-- open: 124, close: 123 --><font class="italic">string</font><!-- open: 124, close: 124 --> <!-- MATCHED MATCHED MATCHED --> with the order of characters reversed.
This will reverse a 1-dimensional array of any type.
</div>

<div class='defun' id='string-nreverse'>
  <font class='exdent'>
    <font class='funcname'>string-nreverse </font>
    <font class='italic' color='purple'>string</font>
  </font><br>
	Returns <!-- open: 125, close: 124 --><font class="italic">string</font><!-- open: 125, close: 125 --> <!-- MATCHED MATCHED MATCHED --> with the order of characters reversed,
smashing the original string, rather than creating a new one.
If <!-- open: 126, close: 125 --><font class="italic">string</font><!-- open: 126, close: 126 --> <!-- MATCHED MATCHED MATCHED --> is a number, it is simply
returned without consing up a string.
This will reverse a 1-dimensional array of any type.
</div>

<div class='defun' id='string-search-char'>
  <font class='exdent'>
    <font class='funcname'>string-search-char </font>
    <font class='italic' color='purple'>char string &optional (from 0) to</font>
  </font><br>
<!-- open: 127, close: 126 --><font class="lisp">string-search-char</font><!-- open: 127, close: 127 --> <!-- MATCHED MATCHED MATCHED --> searches through <!-- open: 128, close: 127 --><font class="italic">string</font><!-- open: 128, close: 128 --> <!-- MATCHED MATCHED MATCHED --> starting at the index <!-- open: 129, close: 128 --><font class="italic">from</font><!-- open: 129, close: 129 --> <!-- MATCHED MATCHED MATCHED -->,
which defaults to the beginning, and returns the index of the first
character which is <!-- open: 130, close: 129 --><font class="lisp">char-equal</font><!-- open: 130, close: 130 --> <!-- MATCHED MATCHED MATCHED --> to <!-- open: 131, close: 130 --><font class="italic">char</font><!-- open: 131, close: 131 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 132, close: 131 --><font class="lisp">nil</font><!-- open: 132, close: 132 --> <!-- MATCHED MATCHED MATCHED --> if none is found.
If the <!-- open: 133, close: 132 --><font class="italic">to</font><!-- open: 133, close: 133 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it is used in place of <!-- open: 134, close: 133 --><font class="lisp">(string-length <!-- open: 135, close: 133 --><font class="italic">string</font><!-- open: 135, close: 134 -->)</font><!-- open: 135, close: 135 --> <!-- MATCHED MATCHED MATCHED -->
to limit the extent of the search.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-search-char 101 "banana") =&gt; 1
</pre>
</div>

<div class='defun' id='%string-search-char'>
  <font class='exdent'>
    <font class='funcname'>%string-search-char </font>
    <font class='italic' color='purple'>char string from to</font>
  </font><br>
<!-- open: 136, close: 135 --><font class="lisp">%string-search-char</font><!-- open: 136, close: 136 --> <!-- MATCHED MATCHED MATCHED --> is the microcode primitive which <!-- open: 137, close: 136 --><font class="lisp">string-search-char</font><!-- open: 137, close: 137 --> <!-- MATCHED MATCHED MATCHED -->
and other functions call.  <!-- open: 138, close: 137 --><font class="italic">string</font><!-- open: 138, close: 138 --> <!-- MATCHED MATCHED MATCHED --> must be an array and <!-- open: 139, close: 138 --><font class="italic">char</font><!-- open: 139, close: 139 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 140, close: 139 --><font class="italic">from</font><!-- open: 140, close: 140 --> <!-- MATCHED MATCHED MATCHED -->,
and <!-- open: 141, close: 140 --><font class="italic">to</font><!-- open: 141, close: 141 --> <!-- MATCHED MATCHED MATCHED --> must be fixnums.  Except for this lack of type-coercion, and the fact
that none of the arguments is optional, <!-- open: 142, close: 141 --><font class="lisp">%string-search-char</font><!-- open: 142, close: 142 --> <!-- MATCHED MATCHED MATCHED --> is the same as
<!-- open: 143, close: 142 --><font class="lisp">string-search-char</font><!-- open: 143, close: 143 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='string-search-not-char'>
  <font class='exdent'>
    <font class='funcname'>string-search-not-char </font>
    <font class='italic' color='purple'>char string &optional (from 0) to</font>
  </font><br>
<!-- open: 144, close: 143 --><font class="lisp">string-search-not-char</font><!-- open: 144, close: 144 --> <!-- MATCHED MATCHED MATCHED --> searches through <!-- open: 145, close: 144 --><font class="italic">string</font><!-- open: 145, close: 145 --> <!-- MATCHED MATCHED MATCHED --> starting at the index <!-- open: 146, close: 145 --><font class="italic">from</font><!-- open: 146, close: 146 --> <!-- MATCHED MATCHED MATCHED -->,
which defaults to the beginning, and returns the index of the first
character which is <!-- open: 147, close: 146 --><font class="italic">not</font><!-- open: 147, close: 147 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 148, close: 147 --><font class="lisp">char-equal</font><!-- open: 148, close: 148 --> <!-- MATCHED MATCHED MATCHED --> to <!-- open: 149, close: 148 --><font class="italic">char</font><!-- open: 149, close: 149 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 150, close: 149 --><font class="lisp">nil</font><!-- open: 150, close: 150 --> <!-- MATCHED MATCHED MATCHED --> if none is found.
If the <!-- open: 151, close: 150 --><font class="italic">to</font><!-- open: 151, close: 151 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it is used in place of <!-- open: 152, close: 151 --><font class="lisp">(string-length <!-- open: 153, close: 151 --><font class="italic">string</font><!-- open: 153, close: 152 -->)</font><!-- open: 153, close: 153 --> <!-- MATCHED MATCHED MATCHED -->
to limit the extent of the search.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-search-char 102 "banana") =&gt; 1
</pre>
</div>

<div class='defun' id='string-search'>
  <font class='exdent'>
    <font class='funcname'>string-search </font>
    <font class='italic' color='purple'>key string &optional (from 0) to</font>
  </font><br>
<!-- open: 154, close: 153 --><font class="lisp">string-search</font><!-- open: 154, close: 154 --> <!-- MATCHED MATCHED MATCHED --> searches for the string <!-- open: 155, close: 154 --><font class="italic">key</font><!-- open: 155, close: 155 --> <!-- MATCHED MATCHED MATCHED --> in the string
<!-- open: 156, close: 155 --><font class="italic">string</font><!-- open: 156, close: 156 --> <!-- MATCHED MATCHED MATCHED -->.  The search begins at <!-- open: 157, close: 156 --><font class="italic">from</font><!-- open: 157, close: 157 --> <!-- MATCHED MATCHED MATCHED -->, which defaults to the
beginning of <!-- open: 158, close: 157 --><font class="italic">string</font><!-- open: 158, close: 158 --> <!-- MATCHED MATCHED MATCHED -->.  The value returned is the index of the first
character of the first instance of <!-- open: 159, close: 158 --><font class="italic">key</font><!-- open: 159, close: 159 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 160, close: 159 --><font class="lisp">nil</font><!-- open: 160, close: 160 --> <!-- MATCHED MATCHED MATCHED --> if none is
found.
If the <!-- open: 161, close: 160 --><font class="italic">to</font><!-- open: 161, close: 161 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it is used in place of <!-- open: 162, close: 161 --><font class="lisp">(string-length <!-- open: 163, close: 161 --><font class="italic">string</font><!-- open: 163, close: 162 -->)</font><!-- open: 163, close: 163 --> <!-- MATCHED MATCHED MATCHED -->
to limit the extent of the search.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-search "an" "banana") =&gt; 1
(string-search "an" "banana" 2) =&gt; 3
</pre>
</div>

<div class='defun' id='string-search-set'>
  <font class='exdent'>
    <font class='funcname'>string-search-set </font>
    <font class='italic' color='purple'>char-list string &optional (from 0) to</font>
  </font><br>
<!-- open: 164, close: 163 --><font class="lisp">string-search-set</font><!-- open: 164, close: 164 --> <!-- MATCHED MATCHED MATCHED --> searches through <!-- open: 165, close: 164 --><font class="italic">string</font><!-- open: 165, close: 165 --> <!-- MATCHED MATCHED MATCHED --> looking for
a character which is in <!-- open: 166, close: 165 --><font class="italic">char-list</font><!-- open: 166, close: 166 --> <!-- MATCHED MATCHED MATCHED -->.  The search begins at the index <!-- open: 167, close: 166 --><font class="italic">from</font><!-- open: 167, close: 167 --> <!-- MATCHED MATCHED MATCHED -->,
which defaults to the beginning.  It returns the index of the first
character which is <!-- open: 168, close: 167 --><font class="lisp">char-equal</font><!-- open: 168, close: 168 --> <!-- MATCHED MATCHED MATCHED --> to some element of <!-- open: 169, close: 168 --><font class="italic">char-list</font><!-- open: 169, close: 169 --> <!-- MATCHED MATCHED MATCHED -->,
or <!-- open: 170, close: 169 --><font class="lisp">nil</font><!-- open: 170, close: 170 --> <!-- MATCHED MATCHED MATCHED --> if none is found.
If the <!-- open: 171, close: 170 --><font class="italic">to</font><!-- open: 171, close: 171 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it is used in place of <!-- open: 172, close: 171 --><font class="lisp">(string-length <!-- open: 173, close: 171 --><font class="italic">string</font><!-- open: 173, close: 172 -->)</font><!-- open: 173, close: 173 --> <!-- MATCHED MATCHED MATCHED -->
to limit the extent of the search.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-search-set '(116 117) "banana") =&gt; 2
</pre>
</div>

<div class='defun' id='string-search-not-set'>
  <font class='exdent'>
    <font class='funcname'>string-search-not-set </font>
    <font class='italic' color='purple'>char-list string &optional (from 0) to</font>
  </font><br>
<!-- open: 174, close: 173 --><font class="lisp">string-search-not-set</font><!-- open: 174, close: 174 --> <!-- MATCHED MATCHED MATCHED --> searches through <!-- open: 175, close: 174 --><font class="italic">string</font><!-- open: 175, close: 175 --> <!-- MATCHED MATCHED MATCHED --> looking for
a character which is not in <!-- open: 176, close: 175 --><font class="italic">char-list</font><!-- open: 176, close: 176 --> <!-- MATCHED MATCHED MATCHED -->.  The search begins at the index <!-- open: 177, close: 176 --><font class="italic">from</font><!-- open: 177, close: 177 --> <!-- MATCHED MATCHED MATCHED -->,
which defaults to the beginning.  It returns the index of the first
character which is not <!-- open: 178, close: 177 --><font class="lisp">char-equal</font><!-- open: 178, close: 178 --> <!-- MATCHED MATCHED MATCHED --> to any element of <!-- open: 179, close: 178 --><font class="italic">char-list</font><!-- open: 179, close: 179 --> <!-- MATCHED MATCHED MATCHED -->,
or <!-- open: 180, close: 179 --><font class="lisp">nil</font><!-- open: 180, close: 180 --> <!-- MATCHED MATCHED MATCHED --> if none is found.
If the <!-- open: 181, close: 180 --><font class="italic">to</font><!-- open: 181, close: 181 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it is used in place of <!-- open: 182, close: 181 --><font class="lisp">(string-length <!-- open: 183, close: 181 --><font class="italic">string</font><!-- open: 183, close: 182 -->)</font><!-- open: 183, close: 183 --> <!-- MATCHED MATCHED MATCHED -->
to limit the extent of the search.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-search-not-set '(141 142) "banana") =&gt; 2
</pre>
</div>

<div class='defun' id='string-reverse-search-char'>
  <font class='exdent'>
    <font class='funcname'>string-reverse-search-char </font>
    <font class='italic' color='purple'>char string &optional from (to 0)</font>
  </font><br>
<!-- open: 184, close: 183 --><font class="lisp">string-reverse-search-char</font><!-- open: 184, close: 184 --> <!-- MATCHED MATCHED MATCHED --> searches through <!-- open: 185, close: 184 --><font class="italic">string</font><!-- open: 185, close: 185 --> <!-- MATCHED MATCHED MATCHED --> in reverse order, starting
from the index one less than <!-- open: 186, close: 185 --><font class="italic">from</font><!-- open: 186, close: 186 --> <!-- MATCHED MATCHED MATCHED -->, which defaults to the length of <!-- open: 187, close: 186 --><font class="italic">string</font><!-- open: 187, close: 187 --> <!-- MATCHED MATCHED MATCHED -->,
and returns the index of the first character which is <!-- open: 188, close: 187 --><font class="lisp">char-equal</font><!-- open: 188, close: 188 --> <!-- MATCHED MATCHED MATCHED -->
to <!-- open: 189, close: 188 --><font class="italic">char</font><!-- open: 189, close: 189 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 190, close: 189 --><font class="lisp">nil</font><!-- open: 190, close: 190 --> <!-- MATCHED MATCHED MATCHED --> if none is found.  Note that the index returned
is from the beginning of the string, although the search starts from the end.
If the <!-- open: 191, close: 190 --><font class="italic">to</font><!-- open: 191, close: 191 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it limits the extent of the search.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-reverse-search-char 156 "banana") =&gt; 4
</pre>
</div>

<div class='defun' id='string-reverse-search-not-char'>
  <font class='exdent'>
    <font class='funcname'>string-reverse-search-not-char </font>
    <font class='italic' color='purple'>char string &optional from (to 0)</font>
  </font><br>
<!-- open: 192, close: 191 --><font class="lisp">string-reverse-search-not-char</font><!-- open: 192, close: 192 --> <!-- MATCHED MATCHED MATCHED --> searches through <!-- open: 193, close: 192 --><font class="italic">string</font><!-- open: 193, close: 193 --> <!-- MATCHED MATCHED MATCHED --> in reverse order, starting
from the index one less than <!-- open: 194, close: 193 --><font class="italic">from</font><!-- open: 194, close: 194 --> <!-- MATCHED MATCHED MATCHED -->, which defaults to the length of <!-- open: 195, close: 194 --><font class="italic">string</font><!-- open: 195, close: 195 --> <!-- MATCHED MATCHED MATCHED -->,
and returns the index of the first character which is <!-- open: 196, close: 195 --><font class="italic">not</font><!-- open: 196, close: 196 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 197, close: 196 --><font class="lisp">char-equal</font><!-- open: 197, close: 197 --> <!-- MATCHED MATCHED MATCHED -->
to <!-- open: 198, close: 197 --><font class="italic">char</font><!-- open: 198, close: 198 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 199, close: 198 --><font class="lisp">nil</font><!-- open: 199, close: 199 --> <!-- MATCHED MATCHED MATCHED --> if none is found.  Note that the index returned
is from the beginning of the string, although the search starts from the end.
If the <!-- open: 200, close: 199 --><font class="italic">to</font><!-- open: 200, close: 200 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it limits the extent of the search.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-reverse-search-not-char 101 "banana") =&gt; 4
</pre>
</div>

<div class='defun' id='string-reverse-search'>
  <font class='exdent'>
    <font class='funcname'>string-reverse-search </font>
    <font class='italic' color='purple'>key string &optional from (to 0)</font>
  </font><br>
<!-- open: 201, close: 200 --><font class="lisp">string-reverse-search</font><!-- open: 201, close: 201 --> <!-- MATCHED MATCHED MATCHED --> searches for the string <!-- open: 202, close: 201 --><font class="italic">key</font><!-- open: 202, close: 202 --> <!-- MATCHED MATCHED MATCHED --> in the string <!-- open: 203, close: 202 --><font class="italic">string</font><!-- open: 203, close: 203 --> <!-- MATCHED MATCHED MATCHED -->.
The search proceeds in reverse order, starting
from the index one less than <!-- open: 204, close: 203 --><font class="italic">from</font><!-- open: 204, close: 204 --> <!-- MATCHED MATCHED MATCHED -->, which defaults to the length of <!-- open: 205, close: 204 --><font class="italic">string</font><!-- open: 205, close: 205 --> <!-- MATCHED MATCHED MATCHED -->,
and returns the index of the first (leftmost) character of the first instance found,
or <!-- open: 206, close: 205 --><font class="lisp">nil</font><!-- open: 206, close: 206 --> <!-- MATCHED MATCHED MATCHED --> if none is found.  Note that the index returned
is from the beginning of the string, although the search starts from the end.
The <!-- open: 207, close: 206 --><font class="italic">from</font><!-- open: 207, close: 207 --> <!-- MATCHED MATCHED MATCHED --> condition, restated, is that the instance of <!-- open: 208, close: 207 --><font class="italic">key</font><!-- open: 208, close: 208 --> <!-- MATCHED MATCHED MATCHED --> found
is the rightmost one whose rightmost character is before the <!-- open: 209, close: 208 --><font class="italic">from</font><!-- open: 209, close: 209 --> <!-- MATCHED MATCHED MATCHED -->'th character
of <!-- open: 210, close: 209 --><font class="italic">string</font><!-- open: 210, close: 210 --> <!-- MATCHED MATCHED MATCHED -->.
If the <!-- open: 211, close: 210 --><font class="italic">to</font><!-- open: 211, close: 211 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it limits the extent of the search.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(string-reverse-search "na" "banana") =&gt; 4
</pre>
</div>

<div class='defun' id='string-reverse-search-set'>
  <font class='exdent'>
    <font class='funcname'>string-reverse-search-set </font>
    <font class='italic' color='purple'>char-list string &optional from (to 0)</font>
  </font><br>
<!-- open: 212, close: 211 --><font class="lisp">string-reverse-search-set</font><!-- open: 212, close: 212 --> <!-- MATCHED MATCHED MATCHED --> searches through <!-- open: 213, close: 212 --><font class="italic">string</font><!-- open: 213, close: 213 --> <!-- MATCHED MATCHED MATCHED --> in reverse order, starting
from the index one less than <!-- open: 214, close: 213 --><font class="italic">from</font><!-- open: 214, close: 214 --> <!-- MATCHED MATCHED MATCHED -->, which defaults to the length of <!-- open: 215, close: 214 --><font class="italic">string</font><!-- open: 215, close: 215 --> <!-- MATCHED MATCHED MATCHED -->,
and returns the index of the first character which is <!-- open: 216, close: 215 --><font class="lisp">char-equal</font><!-- open: 216, close: 216 --> <!-- MATCHED MATCHED MATCHED -->
to some element of <!-- open: 217, close: 216 --><font class="italic">char-list</font><!-- open: 217, close: 217 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 218, close: 217 --><font class="lisp">nil</font><!-- open: 218, close: 218 --> <!-- MATCHED MATCHED MATCHED --> if none is found.
Note that the index returned
is from the beginning of the string, although the search starts from the end.
If the <!-- open: 219, close: 218 --><font class="italic">to</font><!-- open: 219, close: 219 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it limits the extent of the search.
<pre class='lisp'>
(string-reverse-search-set '(141 142) "banana") =&gt; 5
</pre>
</div>

<div class='defun' id='string-reverse-search-not-set'>
  <font class='exdent'>
    <font class='funcname'>string-reverse-search-not-set </font>
    <font class='italic' color='purple'>char-list string &optional from (to 0)</font>
  </font><br>
<!-- open: 220, close: 219 --><font class="lisp">string-reverse-search-not-set</font><!-- open: 220, close: 220 --> <!-- MATCHED MATCHED MATCHED --> searches through <!-- open: 221, close: 220 --><font class="italic">string</font><!-- open: 221, close: 221 --> <!-- MATCHED MATCHED MATCHED --> in reverse order, starting
from the index one less than <!-- open: 222, close: 221 --><font class="italic">from</font><!-- open: 222, close: 222 --> <!-- MATCHED MATCHED MATCHED -->, which defaults to the length of <!-- open: 223, close: 222 --><font class="italic">string</font><!-- open: 223, close: 223 --> <!-- MATCHED MATCHED MATCHED -->,
and returns the index of the first character which is not <!-- open: 224, close: 223 --><font class="lisp">char-equal</font><!-- open: 224, close: 224 --> <!-- MATCHED MATCHED MATCHED -->
to any element of <!-- open: 225, close: 224 --><font class="italic">char-list</font><!-- open: 225, close: 225 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 226, close: 225 --><font class="lisp">nil</font><!-- open: 226, close: 226 --> <!-- MATCHED MATCHED MATCHED --> if none is found.
Note that the index returned
is from the beginning of the string, although the search starts from the end.
If the <!-- open: 227, close: 226 --><font class="italic">to</font><!-- open: 227, close: 227 --> <!-- MATCHED MATCHED MATCHED --> argument is supplied, it limits the extent of the search.
<pre class='lisp'>
(string-reverse-search-not-set '(141 156) "banana") =&gt; 0
</pre>
</div>

See also <!-- open: 228, close: 227 --><font class="lisp">intern</font><!-- open: 228, close: 228 --> <!-- MATCHED MATCHED MATCHED --> (<font color='red'>LINK:(</font>intern-fun)), which given a string will return "the" symbol
with that print name.

<div class='section' id='11.2'>11.2 String Manipulation</div>
The special forms in this section allow you to create I/O streams which
input from or output to a string rather than a real I/O device.
See <font color='red'>LINK:(</font>streams) for documentation of I/O streams.

<div class='defspec' id='with-input-from-string'><font class='exdent'><font class='funcname' id='with-input-from-string'>with-input-from-string</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->The form
<pre class='lisp'>
(with-input-from-string (<!-- open: 229, close: 228 --><font class="italic">var string</font><!-- open: 229, close: 229 --> <!-- MATCHED MATCHED MATCHED -->)
    <!-- open: 230, close: 229 --><font class="italic">body</font><!-- open: 230, close: 230 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
evaluates the forms in <!-- open: 231, close: 230 --><font class="italic">body</font><!-- open: 231, close: 231 --> <!-- MATCHED MATCHED MATCHED --> with the variable <!-- open: 232, close: 231 --><font class="italic">var</font><!-- open: 232, close: 232 --> <!-- MATCHED MATCHED MATCHED --> bound to a stream
which reads characters from the string which is the value of the form
<!-- open: 233, close: 232 --><font class="italic">string</font><!-- open: 233, close: 233 --> <!-- MATCHED MATCHED MATCHED -->.  The value of the special form is the value of the last
form in its body.

The stream is a "downward closure", so be careful what you do with it.
You cannot use it after control leaves the body, and you cannot nest
two <!-- open: 234, close: 233 --><font class="lisp">with-input-from-string</font><!-- open: 234, close: 234 --> <!-- MATCHED MATCHED MATCHED --> special forms and use both streams
since the special-variable bindings associated with the stream will
conflict.  It is done this way to avoid any consing.

After <!-- open: 235, close: 234 --><font class="italic">string</font><!-- open: 235, close: 235 --> <!-- MATCHED MATCHED MATCHED --> you may optionally specify two additional "arguments".
<pre class='lisp'>
(with-input-from-string (<!-- open: 236, close: 235 --><font class="italic">var string index</font><!-- open: 236, close: 236 --> <!-- MATCHED MATCHED MATCHED -->)
    <!-- open: 237, close: 236 --><font class="italic">body</font><!-- open: 237, close: 237 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
uses <!-- open: 238, close: 237 --><font class="italic">index</font><!-- open: 238, close: 238 --> <!-- MATCHED MATCHED MATCHED --> as the starting index into the string, and updates
it when it is done to the index of the first character not read (the
length of the string if all of it was read.)  Since <!-- open: 239, close: 238 --><font class="italic">index</font><!-- open: 239, close: 239 --> <!-- MATCHED MATCHED MATCHED --> is
updated it may not be a general expression; it must be a variable
or a <!-- open: 240, close: 239 --><font class="lisp">setf</font><!-- open: 240, close: 240 --> <!-- MATCHED MATCHED MATCHED -->-able reference.  The <!-- open: 241, close: 240 --><font class="italic">index</font><!-- open: 241, close: 241 --> <!-- MATCHED MATCHED MATCHED --> is not updated
in the event of an abnormal exit from the body, such as a <!-- open: 242, close: 241 --><font class="lisp">*throw</font><!-- open: 242, close: 242 --> <!-- MATCHED MATCHED MATCHED -->.

Use of the <!-- open: 243, close: 242 --><font class="italic">index</font><!-- open: 243, close: 243 --> <!-- MATCHED MATCHED MATCHED --> feature prevents multiple values from being
returned out of the body, currently.

<pre class='lisp'>
(with-input-from-string (<!-- open: 244, close: 243 --><font class="italic">var string index limit</font><!-- open: 244, close: 244 --> <!-- MATCHED MATCHED MATCHED -->)
    <!-- open: 245, close: 244 --><font class="italic">body</font><!-- open: 245, close: 245 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
uses the value of the form <!-- open: 246, close: 245 --><font class="italic">limit</font><!-- open: 246, close: 246 --> <!-- MATCHED MATCHED MATCHED --> in place of the length of the
string if it is not <!-- open: 247, close: 246 --><font class="lisp">nil</font><!-- open: 247, close: 247 --> <!-- MATCHED MATCHED MATCHED -->.  If you want to specify a <!-- open: 248, close: 247 --><font class="italic">limit</font><!-- open: 248, close: 248 --> <!-- MATCHED MATCHED MATCHED -->
but not an <!-- open: 249, close: 248 --><font class="italic">index</font><!-- open: 249, close: 249 --> <!-- MATCHED MATCHED MATCHED -->, put <!-- open: 250, close: 249 --><font class="lisp">nil</font><!-- open: 250, close: 250 --> <!-- MATCHED MATCHED MATCHED --> for <!-- open: 251, close: 250 --><font class="italic">index</font><!-- open: 251, close: 251 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defspec' id='with-output-to-string'><font class='exdent'><font class='funcname' id='with-output-to-string'>with-output-to-string</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->This special form provides a variety of ways to send output to a string
through an i/o stream.

<pre class='lisp'>
(with-output-to-string (<!-- open: 252, close: 251 --><font class="italic">var</font><!-- open: 252, close: 252 --> <!-- MATCHED MATCHED MATCHED -->)
  <!-- open: 253, close: 252 --><font class="italic">body</font><!-- open: 253, close: 253 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
evaluates the forms in <!-- open: 254, close: 253 --><font class="italic">body</font><!-- open: 254, close: 254 --> <!-- MATCHED MATCHED MATCHED --> with <!-- open: 255, close: 254 --><font class="italic">var</font><!-- open: 255, close: 255 --> <!-- MATCHED MATCHED MATCHED --> bound to a stream
which saves the characters output to it in a string.  The value of
the special form is the string.

<pre class='lisp'>
(with-output-to-string (<!-- open: 256, close: 255 --><font class="italic">var string</font><!-- open: 256, close: 256 --> <!-- MATCHED MATCHED MATCHED -->)
  <!-- open: 257, close: 256 --><font class="italic">body</font><!-- open: 257, close: 257 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
will append its output to the string which is the value of the form <!-- open: 258, close: 257 --><font class="italic">string</font><!-- open: 258, close: 258 --> <!-- MATCHED MATCHED MATCHED -->.
(This is like the <!-- open: 259, close: 258 --><font class="lisp">string-nconc</font><!-- open: 259, close: 259 --> <!-- MATCHED MATCHED MATCHED --> function.)
The value returned is the value of the last form in the body, rather than the string.
Multiple values are not returned.  If <!-- open: 260, close: 259 --><font class="italic">string</font><!-- open: 260, close: 260 --> <!-- MATCHED MATCHED MATCHED --> has an array-leader,
element 0 of the array-leader will be used as the fill-pointer.  If <!-- open: 261, close: 260 --><font class="italic">string</font><!-- open: 261, close: 261 --> <!-- MATCHED MATCHED MATCHED -->
is too small to contain all the output, <!-- open: 262, close: 261 --><font class="lisp">adjust-array-size</font><!-- open: 262, close: 262 --> <!-- MATCHED MATCHED MATCHED --> will be used to
make it bigger.

<pre class='lisp'>
(with-output-to-string (<!-- open: 263, close: 262 --><font class="italic">var string index</font><!-- open: 263, close: 263 --> <!-- MATCHED MATCHED MATCHED -->)
  <!-- open: 264, close: 263 --><font class="italic">body</font><!-- open: 264, close: 264 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
is similar to the above except that <!-- open: 265, close: 264 --><font class="italic">index</font><!-- open: 265, close: 265 --> <!-- MATCHED MATCHED MATCHED --> is a variable or <!-- open: 266, close: 265 --><font class="lisp">setf</font><!-- open: 266, close: 266 --> <!-- MATCHED MATCHED MATCHED -->-able
reference which contains the index of the next character to be stored into.
It must be initialized outside the <!-- open: 267, close: 266 --><font class="lisp">with-output-to-string</font><!-- open: 267, close: 267 --> <!-- MATCHED MATCHED MATCHED --> and will be updated
upon normal exit.

The stream is a "downward closure", so be careful what you do with it.
You cannot use it after control leaves the body, and you cannot nest
two <!-- open: 268, close: 267 --><font class="lisp">with-input-from-string</font><!-- open: 268, close: 268 --> <!-- MATCHED MATCHED MATCHED --> special forms and use both streams
since the special-variable bindings associated with the stream will
conflict.  It is done this way to avoid any consing.
</div>

<div class='section' id='11.3'>11.3 Maclisp-compatible Functions</div>
<div class='defun' id='alphalessp'>
  <font class='exdent'>
    <font class='funcname'>alphalessp </font>
    <font class='italic' color='purple'>string1 string2</font>
  </font><br>
<!-- open: 269, close: 268 --><font class="lisp">(alphalessp <!-- open: 270, close: 268 --><font class="italic">string1 string2</font><!-- open: 270, close: 269 -->)</font><!-- open: 270, close: 270 --> <!-- MATCHED MATCHED MATCHED --> is equivalent to
<!-- open: 271, close: 270 --><font class="lisp">(string-lessp <!-- open: 272, close: 270 --><font class="italic">string1 string2</font><!-- open: 272, close: 271 -->)</font><!-- open: 272, close: 272 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='getchar'>
  <font class='exdent'>
    <font class='funcname'>getchar </font>
    <font class='italic' color='purple'>string index</font>
  </font><br>
	Returns the <!-- open: 273, close: 272 --><font class="italic">index</font><!-- open: 273, close: 273 --> <!-- MATCHED MATCHED MATCHED -->'th character of <!-- open: 274, close: 273 --><font class="italic">string</font><!-- open: 274, close: 274 --> <!-- MATCHED MATCHED MATCHED -->
as a symbol.  Note that 1-origin indexing is used.  This function
is mainly for Maclisp compatibility; <!-- open: 275, close: 274 --><font class="lisp">aref</font><!-- open: 275, close: 275 --> <!-- MATCHED MATCHED MATCHED --> should be used
to index into strings (however <!-- open: 276, close: 275 --><font class="lisp">aref</font><!-- open: 276, close: 276 --> <!-- MATCHED MATCHED MATCHED --> will not coerce symbols
or numbers into strings).
</div>

<div class='defun' id='getcharn'>
  <font class='exdent'>
    <font class='funcname'>getcharn </font>
    <font class='italic' color='purple'>string index</font>
  </font><br>
	Returns the <!-- open: 277, close: 276 --><font class="italic">index</font><!-- open: 277, close: 277 --> <!-- MATCHED MATCHED MATCHED -->'th character of <!-- open: 278, close: 277 --><font class="italic">string</font><!-- open: 278, close: 278 --> <!-- MATCHED MATCHED MATCHED -->
as a fixnum.  Note that 1-origin indexing is used.  This function
is mainly for Maclisp compatibility; <!-- open: 279, close: 278 --><font class="lisp">aref</font><!-- open: 279, close: 279 --> <!-- MATCHED MATCHED MATCHED --> should be used
to index into strings (however <!-- open: 280, close: 279 --><font class="lisp">aref</font><!-- open: 280, close: 280 --> <!-- MATCHED MATCHED MATCHED --> will not coerce symbols
or numbers into strings).
</div>

<div class='defun' id='ascii'>
  <font class='exdent'>
    <font class='funcname'>ascii </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
	<!-- open: 281, close: 280 --><font class="lisp">ascii</font><!-- open: 281, close: 281 --> <!-- MATCHED MATCHED MATCHED --> is like <!-- open: 282, close: 281 --><font class="lisp">character</font><!-- open: 282, close: 282 --> <!-- MATCHED MATCHED MATCHED -->, but returns a symbol
whose printname is the character instead of returning a fixnum.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(ascii 101) =&gt; A
(ascii 56) =&gt; /.
</pre>
The symbol returned is interned in the <!-- open: 283, close: 282 --><font class="lisp">user</font><!-- open: 283, close: 283 --> <!-- MATCHED MATCHED MATCHED --> package.
</div>

<div class='defun' id='maknam'>
  <font class='exdent'>
    <font class='funcname'>maknam </font>
    <font class='italic' color='purple'>char-list</font>
  </font><br>
	<!-- open: 284, close: 283 --><font class="lisp">maknam</font><!-- open: 284, close: 284 --> <!-- MATCHED MATCHED MATCHED --> returns
an uninterned symbol whose print-name is a string made up of the characters in <!-- open: 285, close: 284 --><font class="italic">char-list</font><!-- open: 285, close: 285 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(maknam '(a b 60 d)) =&gt; ab0d
</pre>
</div>

<div class='defun' id='implode'>
  <font class='exdent'>
    <font class='funcname'>implode </font>
    <font class='italic' color='purple'>char-list</font>
  </font><br>
	<!-- open: 286, close: 285 --><font class="lisp">implode</font><!-- open: 286, close: 286 --> <!-- MATCHED MATCHED MATCHED --> is like <!-- open: 287, close: 286 --><font class="lisp">maknam</font><!-- open: 287, close: 287 --> <!-- MATCHED MATCHED MATCHED --> except that the returned symbol
is interned in the current package.
</div>

	The <!-- open: 288, close: 287 --><font class="lisp">samepnamep</font><!-- open: 288, close: 288 --> <!-- MATCHED MATCHED MATCHED --> function is also provided; see <font color='red'>LINK:(</font>samepnamep-fun).

<div class='section' id='11.4'>11.4 Formatted Output</div><p class='cindent'><!-- formatted output -->
<!-- Should grind be in here? -->

<div class='defun' id='format'>
  <font class='exdent'>
    <font class='funcname'>format </font>
    <font class='italic' color='purple'>destination control-string &rest args</font>
  </font><br>
<!-- open: 289, close: 288 --><font class="lisp">format</font><!-- open: 289, close: 289 --> <!-- MATCHED MATCHED MATCHED --> is used to produce formatted output.
<!-- open: 290, close: 289 --><font class="lisp">format</font><!-- open: 290, close: 290 --> <!-- MATCHED MATCHED MATCHED --> outputs the characters of <!-- open: 291, close: 290 --><font class="italic">control-string</font><!-- open: 291, close: 291 --> <!-- MATCHED MATCHED MATCHED -->, except
that a tilde ("<u><font color='green'>SAIL</font></u>~") introduces a directive.  The character after
the tilde, possibly preceded by arguments and modifiers, specifies
what kind of formatting is desired.  Some directives use one or more
elements of <!-- open: 292, close: 291 --><font class="italic">args</font><!-- open: 292, close: 292 --> <!-- MATCHED MATCHED MATCHED --> to create their output.

	The output is sent to <!-- open: 293, close: 292 --><font class="italic">destination</font><!-- open: 293, close: 293 --> <!-- MATCHED MATCHED MATCHED -->.  If <!-- open: 294, close: 293 --><font class="italic">destination</font><!-- open: 294, close: 294 --> <!-- MATCHED MATCHED MATCHED --> is
<!-- open: 295, close: 294 --><font class="lisp">nil</font><!-- open: 295, close: 295 --> <!-- MATCHED MATCHED MATCHED -->, a string is created which contains the output; this string is
returned as the value of the call to <!-- open: 296, close: 295 --><font class="lisp">format</font><!-- open: 296, close: 296 --> <!-- MATCHED MATCHED MATCHED -->.  If <!-- open: 297, close: 296 --><font class="italic">destination</font><!-- open: 297, close: 297 --> <!-- MATCHED MATCHED MATCHED --> is
a stream, the output is sent to it.  If <!-- open: 298, close: 297 --><font class="italic">destination</font><!-- open: 298, close: 298 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 299, close: 298 --><font class="lisp">t</font><!-- open: 299, close: 299 --> <!-- MATCHED MATCHED MATCHED -->, the
output is sent to <!-- open: 300, close: 299 --><font class="lisp">standard-output</font><!-- open: 300, close: 300 --> <!-- MATCHED MATCHED MATCHED -->.  If <!-- open: 301, close: 300 --><font class="italic">destination</font><!-- open: 301, close: 301 --> <!-- MATCHED MATCHED MATCHED --> is a string
with an array-leader, such as would be acceptable to <!-- open: 302, close: 301 --><font class="lisp">string-nconc</font><!-- open: 302, close: 302 --> <!-- MATCHED MATCHED MATCHED -->,
the output is added to the end of that string. 

	A directive consists of a tilde, optional decimal numeric parameters
separated by commas, optional colon ("<!-- open: 303, close: 302 --><font class="lisp">:</font><!-- open: 303, close: 303 --> <!-- MATCHED MATCHED MATCHED -->") and atsign ("<!-- open: 304, close: 303 --><font class="lisp">@</font><!-- open: 304, close: 304 --> <!-- MATCHED MATCHED MATCHED -->") modifiers,
and a single character indicating what kind of directive this is.
The alphabetic case of the character is ignored.
Examples of control strings:
<pre class='lisp'>
"~S"        ; <!-- open: 305, close: 304 --><font class="main">This is an S directive with no parameters.</font><!-- open: 305, close: 305 --> <!-- MATCHED MATCHED MATCHED -->
"~3,4:@s"   ; <!-- open: 306, close: 305 --><font class="main">This is an S directive with two parameters, 3 and 4,</font><!-- open: 306, close: 306 --> <!-- MATCHED MATCHED MATCHED -->
            ; <!-- open: 307, close: 306 --><font class="main">   and both the colon and atsign flags.</font><!-- open: 307, close: 307 --> <!-- MATCHED MATCHED MATCHED -->
</pre>

	Sometimes a numeric parameter is used to specify a character,
for instance the padding character in a right- or left-justifying
operation.  In this case a single quote ("<!-- open: 308, close: 307 --><font class="lisp">'</font><!-- open: 308, close: 308 --> <!-- MATCHED MATCHED MATCHED -->") followed by the
desired character may be used as a numeric argument.  For example,
you can use
<pre class='lisp'>
"~5,'0d"
</pre>
to print a decimal number in five columns with leading zeros.

	The kinds of directives will now be described.
<!-- open: 309, close: 308 --><font class="italic">arg</font><!-- open: 309, close: 309 --> <!-- MATCHED MATCHED MATCHED --> will be used to refer to the next argument from <!-- open: 310, close: 309 --><font class="italic">args</font><!-- open: 310, close: 310 --> <!-- MATCHED MATCHED MATCHED -->.
<table>
<tr valign='top'>
<td><font class='lisp'> ~D</font></td><td><!-- open: 311, close: 310 --><font class="italic">arg</font><!-- open: 311, close: 311 --> <!-- MATCHED MATCHED MATCHED -->, a number, is printed as a decimal integer.
<!-- open: 312, close: 311 --><font class="lisp">~<!-- open: 313, close: 311 --><font class="italic">n</font><!-- open: 313, close: 312 -->D</font><!-- open: 313, close: 313 --> <!-- MATCHED MATCHED MATCHED --> uses a column width of <!-- open: 314, close: 313 --><font class="italic">n</font><!-- open: 314, close: 314 --> <!-- MATCHED MATCHED MATCHED -->; spaces are inserted on
the left if the number requires less than <!-- open: 315, close: 314 --><font class="italic">n</font><!-- open: 315, close: 315 --> <!-- MATCHED MATCHED MATCHED --> columns for its digits
and sign.  If the number doesn't fit in <!-- open: 316, close: 315 --><font class="italic">n</font><!-- open: 316, close: 316 --> <!-- MATCHED MATCHED MATCHED --> columns, additional columns
are used as needed. <!-- open: 317, close: 316 --><font class="lisp">~<!-- open: 318, close: 316 --><font class="italic">n</font><!-- open: 318, close: 317 -->,<!-- open: 319, close: 317 --><font class="italic">m</font><!-- open: 319, close: 318 -->D</font><!-- open: 319, close: 319 --> <!-- MATCHED MATCHED MATCHED --> uses <!-- open: 320, close: 319 --><font class="italic">m</font><!-- open: 320, close: 320 --> <!-- MATCHED MATCHED MATCHED --> as the pad character
instead of 40 (space).  If <!-- open: 321, close: 320 --><font class="italic">arg</font><!-- open: 321, close: 321 --> <!-- MATCHED MATCHED MATCHED --> is not a number, it is printed
in <!-- open: 322, close: 321 --><font class="lisp">~A</font><!-- open: 322, close: 322 --> <!-- MATCHED MATCHED MATCHED --> format.
The <!-- open: 323, close: 322 --><font class="lisp">@</font><!-- open: 323, close: 323 --> <!-- MATCHED MATCHED MATCHED --> modifier causes the number's sign to be printed always; the default
is only to print it if the number is negative.
The <!-- open: 324, close: 323 --><font class="lisp">:</font><!-- open: 324, close: 324 --> <!-- MATCHED MATCHED MATCHED --> modifier causes commas to be printed betweens of three digits;
the third numeric parameter may be used to change the character used as the comma.
Thus the most general form of <!-- open: 325, close: 324 --><font class="lisp">~D</font><!-- open: 325, close: 325 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 326, close: 325 --><font class="lisp">~<!-- open: 327, close: 325 --><font class="italic">mincol</font><!-- open: 327, close: 326 -->,<!-- open: 328, close: 326 --><font class="italic">padchar</font><!-- open: 328, close: 327 -->,<!-- open: 329, close: 327 --><font class="italic">commachar</font><!-- open: 329, close: 328 -->D</font><!-- open: 329, close: 329 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~O</font></td><td>This is just like <!-- open: 330, close: 329 --><font class="lisp">~D</font><!-- open: 330, close: 330 --> <!-- MATCHED MATCHED MATCHED --> but prints in octal instead of decimal.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~F</font></td><td><!-- open: 331, close: 330 --><font class="italic">arg</font><!-- open: 331, close: 331 --> <!-- MATCHED MATCHED MATCHED --> is printed in floating point.  <!-- open: 332, close: 331 --><font class="lisp">~<!-- open: 333, close: 331 --><font class="italic">n</font><!-- open: 333, close: 332 -->F</font><!-- open: 333, close: 333 --> <!-- MATCHED MATCHED MATCHED --> rounds <!-- open: 334, close: 333 --><font class="italic">arg</font><!-- open: 334, close: 334 --> <!-- MATCHED MATCHED MATCHED --> to a precision
of <!-- open: 335, close: 334 --><font class="italic">n</font><!-- open: 335, close: 335 --> <!-- MATCHED MATCHED MATCHED --> digits.  The minimum value of <!-- open: 336, close: 335 --><font class="italic">n</font><!-- open: 336, close: 336 --> <!-- MATCHED MATCHED MATCHED --> is 2, since a decimal point is
always printed.  If the magnitude of <!-- open: 337, close: 336 --><font class="italic">arg</font><!-- open: 337, close: 337 --> <!-- MATCHED MATCHED MATCHED --> is too large or too small, it is printed
in exponential notation.  If <!-- open: 338, close: 337 --><font class="italic">arg</font><!-- open: 338, close: 338 --> <!-- MATCHED MATCHED MATCHED --> is not a number, it is printed in
<!-- open: 339, close: 338 --><font class="lisp">~A</font><!-- open: 339, close: 339 --> <!-- MATCHED MATCHED MATCHED --> format.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~E</font></td><td><!-- open: 340, close: 339 --><font class="italic">arg</font><!-- open: 340, close: 340 --> <!-- MATCHED MATCHED MATCHED --> is printed in exponential notation.  This is identical to <!-- open: 341, close: 340 --><font class="lisp">~F</font><!-- open: 341, close: 341 --> <!-- MATCHED MATCHED MATCHED -->,
including the use of a numeric parameter to specify the number of digits,
except that the number is always printed with a trailing exponent,
even if it is within a reasonable range.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~A</font></td><td><!-- open: 342, close: 341 --><font class="italic">arg</font><!-- open: 342, close: 342 --> <!-- MATCHED MATCHED MATCHED -->, any Lisp object, is printed without slashification (like <!-- open: 343, close: 342 --><font class="lisp">princ</font><!-- open: 343, close: 343 --> <!-- MATCHED MATCHED MATCHED -->).
<!-- open: 344, close: 343 --><font class="lisp">~:A</font><!-- open: 344, close: 344 --> <!-- MATCHED MATCHED MATCHED --> prints <!-- open: 345, close: 344 --><font class="lisp">()</font><!-- open: 345, close: 345 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 346, close: 345 --><font class="italic">arg</font><!-- open: 346, close: 346 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 347, close: 346 --><font class="lisp">nil</font><!-- open: 347, close: 347 --> <!-- MATCHED MATCHED MATCHED -->; this is useful when printing
something that is always supposed to be a list.
<!-- open: 348, close: 347 --><font class="lisp">~<!-- open: 349, close: 347 --><font class="italic">n</font><!-- open: 349, close: 348 -->A</font><!-- open: 349, close: 349 --> <!-- MATCHED MATCHED MATCHED --> inserts spaces on the right, if necessary, to make the
column width at least <!-- open: 350, close: 349 --><font class="italic">n</font><!-- open: 350, close: 350 --> <!-- MATCHED MATCHED MATCHED -->.  The <!-- open: 351, close: 350 --><font class="lisp">@</font><!-- open: 351, close: 351 --> <!-- MATCHED MATCHED MATCHED --> modifier causes the spaces
to be inserted on the left rather than the right.
<!-- open: 352, close: 351 --><font class="lisp">~<!-- open: 353, close: 351 --><font class="italic">mincol,colinc,minpad,padchar</font><!-- open: 353, close: 352 -->A</font><!-- open: 353, close: 353 --> <!-- MATCHED MATCHED MATCHED --> is the full form of <!-- open: 354, close: 353 --><font class="lisp">~A</font><!-- open: 354, close: 354 --> <!-- MATCHED MATCHED MATCHED -->,
which allows elaborate control of the padding.
The string is padded on the right with at least <!-- open: 355, close: 354 --><font class="italic">minpad</font><!-- open: 355, close: 355 --> <!-- MATCHED MATCHED MATCHED --> copies
of <!-- open: 356, close: 355 --><font class="italic">padchar</font><!-- open: 356, close: 356 --> <!-- MATCHED MATCHED MATCHED -->; padding characters are then inserted <!-- open: 357, close: 356 --><font class="italic">colinc</font><!-- open: 357, close: 357 --> <!-- MATCHED MATCHED MATCHED --> characters
at a time until the total width is at least <!-- open: 358, close: 357 --><font class="italic">mincol</font><!-- open: 358, close: 358 --> <!-- MATCHED MATCHED MATCHED -->.
The defaults are 0 for <!-- open: 359, close: 358 --><font class="italic">mincol</font><!-- open: 359, close: 359 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 360, close: 359 --><font class="italic">minpad</font><!-- open: 360, close: 360 --> <!-- MATCHED MATCHED MATCHED -->, 1 for <!-- open: 361, close: 360 --><font class="italic">colinc</font><!-- open: 361, close: 361 --> <!-- MATCHED MATCHED MATCHED -->,
and space for <!-- open: 362, close: 361 --><font class="italic">padchar</font><!-- open: 362, close: 362 --> <!-- MATCHED MATCHED MATCHED -->.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~S</font></td><td>This is just like <!-- open: 363, close: 362 --><font class="lisp">~A</font><!-- open: 363, close: 363 --> <!-- MATCHED MATCHED MATCHED -->, but <!-- open: 364, close: 363 --><font class="italic">arg</font><!-- open: 364, close: 364 --> <!-- MATCHED MATCHED MATCHED --> is printed <!-- open: 365, close: 364 --><font class="italic">with</font><!-- open: 365, close: 365 --> <!-- MATCHED MATCHED MATCHED --> slashification
(like <!-- open: 366, close: 365 --><font class="lisp">prin1</font><!-- open: 366, close: 366 --> <!-- MATCHED MATCHED MATCHED --> rather than <!-- open: 367, close: 366 --><font class="lisp">princ</font><!-- open: 367, close: 367 --> <!-- MATCHED MATCHED MATCHED -->).

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~C</font></td><td><!-- open: 368, close: 367 --><font class="lisp">(character <!-- open: 369, close: 367 --><font class="italic">arg</font><!-- open: 369, close: 368 -->)</font><!-- open: 369, close: 369 --> <!-- MATCHED MATCHED MATCHED --> is printed as a keyboard character (see <font color='red'>LINK:(</font>%%kbd)).
Any control bits are printed first by representing them with Greek letters:
alpha (Control), beta (Meta), epsilon (Control and Meta),
lambda (Hyper), pi (Super).
If the character itself is alpha, beta, epsilon, lambda, pi, or equivalence-sign,
then it is preceded by an equivalence-sign to quote it.

With the colon flag (<!-- open: 370, close: 369 --><font class="lisp">~:C</font><!-- open: 370, close: 370 --> <!-- MATCHED MATCHED MATCHED -->), the name of the control bits are spelled out
(e.g. "<!-- open: 371, close: 370 --><font class="lisp">Control-Meta-F</font><!-- open: 371, close: 371 --> <!-- MATCHED MATCHED MATCHED -->"), and also non-printing characters (those in the 200 to 377 range)
are represented by their names (e.g. "<!-- open: 372, close: 371 --><font class="lisp">Return</font><!-- open: 372, close: 372 --> <!-- MATCHED MATCHED MATCHED -->").

With both colon and atsign (<!-- open: 373, close: 372 --><font class="lisp">~:@C</font><!-- open: 373, close: 373 --> <!-- MATCHED MATCHED MATCHED -->), the colon-only format is printed, and then
if the character requires the Top, Front, or Greek key(s) to type it,
this fact is mentioned (e.g. "<!-- open: 374, close: 373 --><font class="lisp">&ge; (Top-L)</font><!-- open: 374, close: 374 --> <!-- MATCHED MATCHED MATCHED -->").

For all three of these formats,
if the character is not a keyboard character but a mouse "character",
it is printed as "Mouse-", the name of the button, "-", and the number of clicks.

With just an atsign (<!-- open: 375, close: 374 --><font class="lisp">~@C</font><!-- open: 375, close: 375 --> <!-- MATCHED MATCHED MATCHED -->), the character is printed in such a way that
the READ function can understand it, using "<!-- open: 376, close: 375 --><font class="lisp">#/</font><!-- open: 376, close: 376 --> <!-- MATCHED MATCHED MATCHED -->" or "<!-- open: 377, close: 376 --><font class="lisp">#\</font><!-- open: 377, close: 377 --> <!-- MATCHED MATCHED MATCHED -->".

Examples:
<pre class='lisp'>
(setq a `(44 1440 403 215 611 ,(dpb 1 %%kbd-mouse 11)))
(format nil "~{&lt;~C&gt;~}" a)  =&gt;
  "&lt;$&gt;&lt; &gt;&lt;&gt;&lt;
&gt;&lt;	&gt;&lt;Mouse-Middle-Twice&gt;"
(format nil "~{&lt;~:C&gt;~}" a)  =&gt;
  "&lt;$&gt;&lt;Control-Meta-Space&gt;&lt;Control-&gt;&lt;Return&gt;&lt;Control-Tab&gt;&lt;Mouse-Middle-Twice&gt;"
(format nil "~{&lt;~:@C&gt;~}" a)  =&gt;
  "&lt;$&gt;&lt;Control-Meta-Space&gt;&lt;Control- (Top-X)&gt;&lt;Return&gt;&lt;Control-Tab&gt;&lt;Mouse-Middle-Twice&gt;"
(format nil "~{&lt;~@C&gt;~}" a)  =&gt;
  "&lt;#//$&gt;&lt;#\SPACE&gt;&lt;#//&gt;&lt;#\RETURN&gt;&lt;#\TAB&gt;&lt;#\MOUSE-M-2&gt;"
</pre>

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~%</font></td><td>Outputs a newline.  <!-- open: 378, close: 377 --><font class="lisp">~<!-- open: 379, close: 377 --><font class="italic">n</font><!-- open: 379, close: 378 -->%</font><!-- open: 379, close: 379 --> <!-- MATCHED MATCHED MATCHED --> outputs <!-- open: 380, close: 379 --><font class="italic">n</font><!-- open: 380, close: 380 --> <!-- MATCHED MATCHED MATCHED --> newlines.
No argument is used.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~&amp;</font></td><td>The <!-- open: 381, close: 380 --><font class="lisp">:fresh-line</font><!-- open: 381, close: 381 --> <!-- MATCHED MATCHED MATCHED --> operation is performed on the output stream.
Unless the stream knows that it is already at the front of a line,
this outputs a newline.  <!-- open: 382, close: 381 --><font class="lisp">~<!-- open: 383, close: 381 --><font class="italic">n</font><!-- open: 383, close: 382 -->&amp;</font><!-- open: 383, close: 383 --> <!-- MATCHED MATCHED MATCHED --> does a <!-- open: 384, close: 383 --><font class="lisp">:fresh-line</font><!-- open: 384, close: 384 --> <!-- MATCHED MATCHED MATCHED --> operation
and then outputs <!-- open: 385, close: 384 --><font class="italic">n-1</font><!-- open: 385, close: 385 --> <!-- MATCHED MATCHED MATCHED --> newlines.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~|</font></td><td>Outputs a formfeed.  <!-- open: 386, close: 385 --><font class="lisp">~<!-- open: 387, close: 385 --><font class="italic">n</font><!-- open: 387, close: 386 -->|</font><!-- open: 387, close: 387 --> <!-- MATCHED MATCHED MATCHED --> outputs <!-- open: 388, close: 387 --><font class="italic">n</font><!-- open: 388, close: 388 --> <!-- MATCHED MATCHED MATCHED --> formfeeds.  With a <!-- open: 389, close: 388 --><font class="lisp">:</font><!-- open: 389, close: 389 --> <!-- MATCHED MATCHED MATCHED -->,
performs a <!-- open: 390, close: 389 --><font class="lisp">:clear-screen</font><!-- open: 390, close: 390 --> <!-- MATCHED MATCHED MATCHED --> operation on the output stream if the stream
supports that operation; otherwise it behaves as if no <!-- open: 391, close: 390 --><font class="lisp">:</font><!-- open: 391, close: 391 --> <!-- MATCHED MATCHED MATCHED --> were present
(outputs formfeed(s)).

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~X</font></td><td>Outputs a space.  <!-- open: 392, close: 391 --><font class="lisp">~<!-- open: 393, close: 391 --><font class="italic">n</font><!-- open: 393, close: 392 -->X</font><!-- open: 393, close: 393 --> <!-- MATCHED MATCHED MATCHED --> outputs <!-- open: 394, close: 393 --><font class="italic">n</font><!-- open: 394, close: 394 --> <!-- MATCHED MATCHED MATCHED --> spaces.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~~</font></td><td>Outputs a tilde.  <!-- open: 395, close: 394 --><font class="lisp">~<!-- open: 396, close: 394 --><font class="italic">n</font><!-- open: 396, close: 395 -->~</font><!-- open: 396, close: 396 --> <!-- MATCHED MATCHED MATCHED --> outputs <!-- open: 397, close: 396 --><font class="italic">n</font><!-- open: 397, close: 397 --> <!-- MATCHED MATCHED MATCHED --> tildes.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~ &lt;CR&gt;</font></td><td>Tilde immediately followed by a carriage return ignores the carriage return
and any whitespace at the beginning of the next line.  With a <!-- open: 398, close: 397 --><font class="lisp">:</font><!-- open: 398, close: 398 --> <!-- MATCHED MATCHED MATCHED -->, the whitespace
is left in place.  With an <!-- open: 399, close: 398 --><font class="lisp">@</font><!-- open: 399, close: 399 --> <!-- MATCHED MATCHED MATCHED -->, the carriage return is left in place.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~*</font></td><td><!-- open: 400, close: 399 --><font class="italic">arg</font><!-- open: 400, close: 400 --> <!-- MATCHED MATCHED MATCHED --> is ignored.  <!-- open: 401, close: 400 --><font class="lisp">~<!-- open: 402, close: 400 --><font class="italic">n</font><!-- open: 402, close: 401 -->*</font><!-- open: 402, close: 402 --> <!-- MATCHED MATCHED MATCHED --> ignores the next <!-- open: 403, close: 402 --><font class="italic">n</font><!-- open: 403, close: 403 --> <!-- MATCHED MATCHED MATCHED --> arguments.
<!-- open: 404, close: 403 --><font class="lisp">~:*</font><!-- open: 404, close: 404 --> <!-- MATCHED MATCHED MATCHED --> "ignores backwards"; that is, it backs up in the list
of arguments so that the argument last processed will be processed
again.  <!-- open: 405, close: 404 --><font class="lisp">~:<!-- open: 406, close: 404 --><font class="italic">n</font><!-- open: 406, close: 405 -->*</font><!-- open: 406, close: 406 --> <!-- MATCHED MATCHED MATCHED --> backs up <!-- open: 407, close: 406 --><font class="italic">n</font><!-- open: 407, close: 407 --> <!-- MATCHED MATCHED MATCHED --> arguments.
When within a <!-- open: 408, close: 407 --><font class="lisp">~{</font><!-- open: 408, close: 408 --> <!-- MATCHED MATCHED MATCHED --> construct, the ignoring (in either direction)
is relative to the list of arguments being processed by the iteration.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~P</font></td><td>If <!-- open: 409, close: 408 --><font class="italic">arg</font><!-- open: 409, close: 409 --> <!-- MATCHED MATCHED MATCHED --> is not <!-- open: 410, close: 409 --><font class="lisp">1</font><!-- open: 410, close: 410 --> <!-- MATCHED MATCHED MATCHED -->, a lower-case s is printed.  ("P" for "plural".)
<!-- open: 411, close: 410 --><font class="lisp">~:P</font><!-- open: 411, close: 411 --> <!-- MATCHED MATCHED MATCHED --> does the same thing, after doing a <!-- open: 412, close: 411 --><font class="lisp">~:*</font><!-- open: 412, close: 412 --> <!-- MATCHED MATCHED MATCHED -->; that is, it prints
a lower-case s if the <!-- open: 413, close: 412 --><font class="italic">last</font><!-- open: 413, close: 413 --> <!-- MATCHED MATCHED MATCHED --> argument was not 1.  <!-- open: 414, close: 413 --><font class="lisp">~@P</font><!-- open: 414, close: 414 --> <!-- MATCHED MATCHED MATCHED --> prints "y"
if the argument is 1, or "ies" if it is not.  <!-- open: 415, close: 414 --><font class="lisp">~:@P</font><!-- open: 415, close: 415 --> <!-- MATCHED MATCHED MATCHED --> does the same thing,
but backs up first.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~T</font></td><td>Spaces over to a given column.  <!-- open: 416, close: 415 --><font class="lisp">~<!-- open: 417, close: 415 --><font class="italic">n</font><!-- open: 417, close: 416 -->,<!-- open: 418, close: 416 --><font class="italic">m</font><!-- open: 418, close: 417 -->T</font><!-- open: 418, close: 418 --> <!-- MATCHED MATCHED MATCHED --> will output
sufficient spaces to move the cursor to column <!-- open: 419, close: 418 --><font class="italic">n</font><!-- open: 419, close: 419 --> <!-- MATCHED MATCHED MATCHED -->.  If the cursor
is already past column <!-- open: 420, close: 419 --><font class="italic">n</font><!-- open: 420, close: 420 --> <!-- MATCHED MATCHED MATCHED -->, it will output spaces to move it to
column <!-- open: 421, close: 420 --><font class="italic">n</font><!-- open: 421, close: 421 --> <!-- MATCHED MATCHED MATCHED -->+<!-- open: 422, close: 421 --><font class="italic">mk</font><!-- open: 422, close: 422 --> <!-- MATCHED MATCHED MATCHED -->, for the smallest integer value <!-- open: 423, close: 422 --><font class="italic">k</font><!-- open: 423, close: 423 --> <!-- MATCHED MATCHED MATCHED --> possible.
<!-- open: 424, close: 423 --><font class="italic">n</font><!-- open: 424, close: 424 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 425, close: 424 --><font class="italic">m</font><!-- open: 425, close: 425 --> <!-- MATCHED MATCHED MATCHED --> default to <!-- open: 426, close: 425 --><font class="lisp">1</font><!-- open: 426, close: 426 --> <!-- MATCHED MATCHED MATCHED -->.  Without the colon flag, <!-- open: 427, close: 426 --><font class="italic">n</font><!-- open: 427, close: 427 --> <!-- MATCHED MATCHED MATCHED --> and
<!-- open: 428, close: 427 --><font class="italic">m</font><!-- open: 428, close: 428 --> <!-- MATCHED MATCHED MATCHED --> are in units of characters; with it, they are in units of pixels.
<!-- open: 429, close: 428 --><font class="italic">Note</font><!-- open: 429, close: 429 --> <!-- MATCHED MATCHED MATCHED -->: this operation <!-- open: 430, close: 429 --><font class="italic">only</font><!-- open: 430, close: 430 --> <!-- MATCHED MATCHED MATCHED --> works properly on streams that support
the <!-- open: 431, close: 430 --><font class="lisp">:read-cursorpos</font><!-- open: 431, close: 431 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 432, close: 431 --><font class="lisp">:set-cursorpos</font><!-- open: 432, close: 432 --> <!-- MATCHED MATCHED MATCHED --> stream operations
(see <font color='red'>LINK:(</font>read-cursorpos)).  On other streams (and when <!-- open: 433, close: 432 --><font class="lisp">format</font><!-- open: 433, close: 433 --> <!-- MATCHED MATCHED MATCHED --> is creating
a string), any <!-- open: 434, close: 433 --><font class="lisp">~T</font><!-- open: 434, close: 434 --> <!-- MATCHED MATCHED MATCHED --> operation will simply output two spaces.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~R</font></td><td>If there is no parameter, then <!-- open: 435, close: 434 --><font class="italic">arg</font><!-- open: 435, close: 435 --> <!-- MATCHED MATCHED MATCHED --> is printed as a cardinal English number, e.g. four.
With the colon modifier, <!-- open: 436, close: 435 --><font class="italic">arg</font><!-- open: 436, close: 436 --> <!-- MATCHED MATCHED MATCHED --> is printed as an ordinal number, e.g. fourth.
With the atsign modifier, <!-- open: 437, close: 436 --><font class="italic">arg</font><!-- open: 437, close: 437 --> <!-- MATCHED MATCHED MATCHED --> is printed as a Roman numeral, e.g. IV.
With both atsign and colon, <!-- open: 438, close: 437 --><font class="italic">arg</font><!-- open: 438, close: 438 --> <!-- MATCHED MATCHED MATCHED --> is printed as an old Roman numeral, e.g. IIII.

If there is a parameter, then it is the radix in which to print the number.
The flags and any remaining parameters are used as for the <!-- open: 439, close: 438 --><font class="lisp">~D</font><!-- open: 439, close: 439 --> <!-- MATCHED MATCHED MATCHED --> directive.
Indeed, <!-- open: 440, close: 439 --><font class="lisp">~D</font><!-- open: 440, close: 440 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 441, close: 440 --><font class="lisp">~10R</font><!-- open: 441, close: 441 --> <!-- MATCHED MATCHED MATCHED -->.  The full form here is therefore
<!-- open: 442, close: 441 --><font class="lisp">~<!-- open: 443, close: 441 --><font class="italic">radix</font><!-- open: 443, close: 442 -->,<!-- open: 444, close: 442 --><font class="italic">mincol</font><!-- open: 444, close: 443 -->,<!-- open: 445, close: 443 --><font class="italic">padchar</font><!-- open: 445, close: 444 -->,<!-- open: 446, close: 444 --><font class="italic">commachar</font><!-- open: 446, close: 445 -->R</font><!-- open: 446, close: 446 --> <!-- MATCHED MATCHED MATCHED -->.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~<!-- open: 447, close: 446 --><font class="italic">n</font><!-- open: 447, close: 447 --> <!-- MATCHED MATCHED MATCHED -->&thinsp;G</font></td><td>"Goes to" the <!-- open: 448, close: 447 --><font class="italic">n</font><!-- open: 448, close: 448 --> <!-- MATCHED MATCHED MATCHED -->th argument.  <!-- open: 449, close: 448 --><font class="lisp">~0G</font><!-- open: 449, close: 449 --> <!-- MATCHED MATCHED MATCHED --> goes back to the
first argument in <!-- open: 450, close: 449 --><font class="italic">args</font><!-- open: 450, close: 450 --> <!-- MATCHED MATCHED MATCHED -->.  Directives after a <!-- open: 451, close: 450 --><font class="lisp">~<!-- open: 452, close: 450 --><font class="italic">n</font><!-- open: 452, close: 451 -->G</font><!-- open: 452, close: 452 --> <!-- MATCHED MATCHED MATCHED -->
will take sequential arguments after the one gone to.
When within a <!-- open: 453, close: 452 --><font class="lisp">~{</font><!-- open: 453, close: 453 --> <!-- MATCHED MATCHED MATCHED --> construct, the "goto"
is relative to the list of arguments being processed by the iteration.
This is an "absolute goto"; for a "relative goto", see <!-- open: 454, close: 453 --><font class="lisp">~*</font><!-- open: 454, close: 454 --> <!-- MATCHED MATCHED MATCHED -->.

</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> ~[<!-- open: 455, close: 454 --><font class="italic">str0</font><!-- open: 455, close: 455 --> <!-- MATCHED MATCHED MATCHED -->~;<!-- open: 456, close: 455 --><font class="italic">str1</font><!-- open: 456, close: 456 --> <!-- MATCHED MATCHED MATCHED -->~;<!-- open: 457, close: 456 --><font class="italic">...</font><!-- open: 457, close: 457 --> <!-- MATCHED MATCHED MATCHED -->~;<!-- open: 458, close: 457 --><font class="italic">strn</font><!-- open: 458, close: 458 --> <!-- MATCHED MATCHED MATCHED -->~]</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>This is a set of alternative control strings.  The alternatives
(called <!-- open: 459, close: 458 --><font class="italic">clauses</font><!-- open: 459, close: 459 --> <!-- MATCHED MATCHED MATCHED -->)
are separated by <!-- open: 460, close: 459 --><font class="lisp">~;</font><!-- open: 460, close: 460 --> <!-- MATCHED MATCHED MATCHED --> and the construct is terminated by <!-- open: 461, close: 460 --><font class="lisp">~]</font><!-- open: 461, close: 461 --> <!-- MATCHED MATCHED MATCHED -->.
For example, "<!-- open: 462, close: 461 --><font class="lisp">~[Siamese ~;Manx ~;Persian ~;Tortoise-Shell ~;Tiger
~;Yu-Hsiang ~]kitty</font><!-- open: 462, close: 462 --> <!-- MATCHED MATCHED MATCHED -->".  The <!-- open: 463, close: 462 --><font class="italic">arg</font><!-- open: 463, close: 463 --> <!-- MATCHED MATCHED MATCHED -->th
alternative is selected; <!-- open: 464, close: 463 --><font class="lisp">0</font><!-- open: 464, close: 464 --> <!-- MATCHED MATCHED MATCHED --> selects the first.
If a numeric parameter is given (i.e. <!-- open: 465, close: 464 --><font class="lisp">~<!-- open: 466, close: 464 --><font class="italic">n</font><!-- open: 466, close: 465 -->[</font><!-- open: 466, close: 466 --> <!-- MATCHED MATCHED MATCHED -->),
then the parameter is used instead of an argument
(this is useful only if the parameter is "<!-- open: 467, close: 466 --><font class="lisp">#</font><!-- open: 467, close: 467 --> <!-- MATCHED MATCHED MATCHED -->").
If <!-- open: 468, close: 467 --><font class="italic">arg</font><!-- open: 468, close: 468 --> <!-- MATCHED MATCHED MATCHED --> is out of range no alternative is selected.
After the selected alternative has been processed, the control string
continues after the <!-- open: 469, close: 468 --><font class="lisp">~]</font><!-- open: 469, close: 469 --> <!-- MATCHED MATCHED MATCHED -->.

~[<!-- open: 470, close: 469 --><font class="italic">str0</font><!-- open: 470, close: 470 --> <!-- MATCHED MATCHED MATCHED -->~;<!-- open: 471, close: 470 --><font class="italic">str1</font><!-- open: 471, close: 471 --> <!-- MATCHED MATCHED MATCHED -->~;<!-- open: 472, close: 471 --><font class="italic">...</font><!-- open: 472, close: 472 --> <!-- MATCHED MATCHED MATCHED -->~;<!-- open: 473, close: 472 --><font class="italic">strn</font><!-- open: 473, close: 473 --> <!-- MATCHED MATCHED MATCHED -->~:;<!-- open: 474, close: 473 --><font class="italic">default</font><!-- open: 474, close: 474 --> <!-- MATCHED MATCHED MATCHED -->~] has a default case.
If the <!-- open: 475, close: 474 --><font class="italic">last</font><!-- open: 475, close: 475 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 476, close: 475 --><font class="lisp">~;</font><!-- open: 476, close: 476 --> <!-- MATCHED MATCHED MATCHED --> used to separate clauses
is instead <!-- open: 477, close: 476 --><font class="lisp">~:;</font><!-- open: 477, close: 477 --> <!-- MATCHED MATCHED MATCHED -->, then the last clause is an "else" clause,
which is performed if no other clause is selected.
For example, "<!-- open: 478, close: 477 --><font class="lisp">~[Siamese ~;Manx ~;Persian ~;Tortoise-Shell ~;Tiger
~;Yu-Hsiang ~:;Unknown ~] kitty</font><!-- open: 478, close: 478 --> <!-- MATCHED MATCHED MATCHED -->".

~[~<!-- open: 479, close: 478 --><font class="italic">tag00</font><!-- open: 479, close: 479 --> <!-- MATCHED MATCHED MATCHED -->,<!-- open: 480, close: 479 --><font class="italic">tag01</font><!-- open: 480, close: 480 --> <!-- MATCHED MATCHED MATCHED -->,<!-- open: 481, close: 480 --><font class="italic">...</font><!-- open: 481, close: 481 --> <!-- MATCHED MATCHED MATCHED -->;<!-- open: 482, close: 481 --><font class="italic">str0</font><!-- open: 482, close: 482 --> <!-- MATCHED MATCHED MATCHED -->~<!-- open: 483, close: 482 --><font class="italic">tag10</font><!-- open: 483, close: 483 --> <!-- MATCHED MATCHED MATCHED -->,<!-- open: 484, close: 483 --><font class="italic">...</font><!-- open: 484, close: 484 --> <!-- MATCHED MATCHED MATCHED -->;<!-- open: 485, close: 484 --><font class="italic">str1...</font><!-- open: 485, close: 485 --> <!-- MATCHED MATCHED MATCHED -->~]
allows the clauses to have explicit tags.  The parameters to each <!-- open: 486, close: 485 --><font class="lisp">~;</font><!-- open: 486, close: 486 --> <!-- MATCHED MATCHED MATCHED -->
are numeric tags for the clause which follows it.  That clause is processed
which has a tag matching the argument.  If <!-- open: 487, close: 486 --><font class="lisp">~:<!-- open: 488, close: 486 --><font class="italic">a1</font><!-- open: 488, close: 487 -->,<!-- open: 489, close: 487 --><font class="italic">a2</font><!-- open: 489, close: 488 -->,<!-- open: 490, close: 488 --><font class="italic">b1</font><!-- open: 490, close: 489 -->,<!-- open: 491, close: 489 --><font class="italic">b2</font><!-- open: 491, close: 490 -->,<!-- open: 492, close: 490 --><font class="italic">...</font><!-- open: 492, close: 491 -->;</font><!-- open: 492, close: 492 --> <!-- MATCHED MATCHED MATCHED -->
is used, then the following clause is tagged not by single values but
by ranges of values <!-- open: 493, close: 492 --><font class="italic">a1</font><!-- open: 493, close: 493 --> <!-- MATCHED MATCHED MATCHED --> through <!-- open: 494, close: 493 --><font class="italic">a2</font><!-- open: 494, close: 494 --> <!-- MATCHED MATCHED MATCHED --> (inclusive), <!-- open: 495, close: 494 --><font class="italic">b1</font><!-- open: 495, close: 495 --> <!-- MATCHED MATCHED MATCHED --> through <!-- open: 496, close: 495 --><font class="italic">b2</font><!-- open: 496, close: 496 --> <!-- MATCHED MATCHED MATCHED -->, etc.
<!-- open: 497, close: 496 --><font class="lisp">~:;</font><!-- open: 497, close: 497 --> <!-- MATCHED MATCHED MATCHED --> with no parameters may be used at the end to denote a default clause.
For example, "<!-- open: 498, close: 497 --><font class="lisp">~[~'+,'-,'*,'//;operator ~'A,'Z,'a,'z;letter ~'0,'9;digit ~:;other ~]</font><!-- open: 498, close: 498 --> <!-- MATCHED MATCHED MATCHED -->".

<!-- open: 499, close: 498 --><font class="lisp">~:[<!-- open: 500, close: 498 --><font class="italic">false</font><!-- open: 500, close: 499 -->~;<!-- open: 501, close: 499 --><font class="italic">true</font><!-- open: 501, close: 500 -->~]</font><!-- open: 501, close: 501 --> <!-- MATCHED MATCHED MATCHED --> selects the <!-- open: 502, close: 501 --><font class="italic">false</font><!-- open: 502, close: 502 --> <!-- MATCHED MATCHED MATCHED --> control string
if <!-- open: 503, close: 502 --><font class="italic">arg</font><!-- open: 503, close: 503 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 504, close: 503 --><font class="lisp">nil</font><!-- open: 504, close: 504 --> <!-- MATCHED MATCHED MATCHED -->, and selects the <!-- open: 505, close: 504 --><font class="italic">true</font><!-- open: 505, close: 505 --> <!-- MATCHED MATCHED MATCHED --> control string otherwise.

<!-- open: 506, close: 505 --><font class="lisp">~@[<!-- open: 507, close: 505 --><font class="italic">true</font><!-- open: 507, close: 506 -->~]</font><!-- open: 507, close: 507 --> <!-- MATCHED MATCHED MATCHED --> tests the argument.  If it is not <!-- open: 508, close: 507 --><font class="lisp">nil</font><!-- open: 508, close: 508 --> <!-- MATCHED MATCHED MATCHED -->,
then the argument is not used up, but is the next one to be processed,
and the one clause is processed.
If it is <!-- open: 509, close: 508 --><font class="lisp">nil</font><!-- open: 509, close: 509 --> <!-- MATCHED MATCHED MATCHED -->, then the argument is used up, and the clause is not processed.
<pre class='lisp'>
(setq prinlevel nil prinlength 5)
(format nil "~@[ PRINLEVEL=~D~]~@[ PRINLENGTH=~D]" prinlevel prinlength)
   =&gt;  " PRINLENGTH=5"
</pre>

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~;</font></td><td>Separates clauses in <!-- open: 510, close: 509 --><font class="lisp">~[</font><!-- open: 510, close: 510 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 511, close: 510 --><font class="lisp">~&lt;</font><!-- open: 511, close: 511 --> <!-- MATCHED MATCHED MATCHED --> constructions.  It is undefined elsewhere.

</td></tr>
<tr valign='top'>
<td><font class='lisp'> ~]</font></td><td>Terminates a <!-- open: 512, close: 511 --><font class="lisp">~[</font><!-- open: 512, close: 512 --> <!-- MATCHED MATCHED MATCHED -->.  It is undefined elsewhere.
</td></tr><!-- item_ --></table><!-- end table -->


<tr valign='top'>
<td><font class='lisp'> ~{<!-- open: 513, close: 512 --><font class="italic">str</font><!-- open: 513, close: 513 --> <!-- MATCHED MATCHED MATCHED -->~}</font></td><td>This is an iteration construct.  The argument should be a list,
which is used as a set of arguments as if for a recursive call to <!-- open: 514, close: 513 --><font class="lisp">format</font><!-- open: 514, close: 514 --> <!-- MATCHED MATCHED MATCHED -->.
The string <!-- open: 515, close: 514 --><font class="italic">str</font><!-- open: 515, close: 515 --> <!-- MATCHED MATCHED MATCHED --> is used repeatedly as the control string.
Each iteration can absorb as many elements of the list as it likes.
If before any iteration step the list is empty, then the iteration is terminated.
Also, if a numeric parameter <!-- open: 516, close: 515 --><font class="italic">n</font><!-- open: 516, close: 516 --> <!-- MATCHED MATCHED MATCHED --> is given, then there will be at most <!-- open: 517, close: 516 --><font class="italic">n</font><!-- open: 517, close: 517 --> <!-- MATCHED MATCHED MATCHED -->
repetitions of processing of <!-- open: 518, close: 517 --><font class="italic">str</font><!-- open: 518, close: 518 --> <!-- MATCHED MATCHED MATCHED -->.

<!-- open: 519, close: 518 --><font class="lisp">~:{<!-- open: 520, close: 518 --><font class="italic">str</font><!-- open: 520, close: 519 -->~}</font><!-- open: 520, close: 520 --> <!-- MATCHED MATCHED MATCHED --> is similar, but the argument should be a list of sublists.
At each repetition step one sublist is used as the set of arguments for
processing <!-- open: 521, close: 520 --><font class="italic">str</font><!-- open: 521, close: 521 --> <!-- MATCHED MATCHED MATCHED -->; on the next repetition a new sublist is used, whether
or not all of the last sublist had been processed.

<!-- open: 522, close: 521 --><font class="lisp">~@{<!-- open: 523, close: 521 --><font class="italic">str</font><!-- open: 523, close: 522 -->~}</font><!-- open: 523, close: 523 --> <!-- MATCHED MATCHED MATCHED --> is similar to <!-- open: 524, close: 523 --><font class="lisp">~{<!-- open: 525, close: 523 --><font class="italic">str</font><!-- open: 525, close: 524 -->~}</font><!-- open: 525, close: 525 --> <!-- MATCHED MATCHED MATCHED -->, but instead of
using one argument which is a list, all the remaining arguments
are used as the list of arguments for the iteration.

<!-- open: 526, close: 525 --><font class="lisp">~:@{<!-- open: 527, close: 525 --><font class="italic">str</font><!-- open: 527, close: 526 -->~}</font><!-- open: 527, close: 527 --> <!-- MATCHED MATCHED MATCHED --> combines the features of <!-- open: 528, close: 527 --><font class="lisp">~:{<!-- open: 529, close: 527 --><font class="italic">str</font><!-- open: 529, close: 528 -->~}</font><!-- open: 529, close: 529 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 530, close: 529 --><font class="lisp">~@{<!-- open: 531, close: 529 --><font class="italic">str</font><!-- open: 531, close: 530 -->~}</font><!-- open: 531, close: 531 --> <!-- MATCHED MATCHED MATCHED -->.
All the remaining arguments
are used, and each one must be a list.
On each iteration one argument is used as a list of arguments.

Terminating the repetition construct with <!-- open: 532, close: 531 --><font class="lisp">~:}</font><!-- open: 532, close: 532 --> <!-- MATCHED MATCHED MATCHED --> instead of <!-- open: 533, close: 532 --><font class="lisp">~}</font><!-- open: 533, close: 533 --> <!-- MATCHED MATCHED MATCHED -->
forces <!-- open: 534, close: 533 --><font class="italic">str</font><!-- open: 534, close: 534 --> <!-- MATCHED MATCHED MATCHED --> to be processed at least once even if the initial
list of arguments is null (however, it will not override an explicit
numeric parameter of zero).

If <!-- open: 535, close: 534 --><font class="italic">str</font><!-- open: 535, close: 535 --> <!-- MATCHED MATCHED MATCHED --> is null, then an argument is used as <!-- open: 536, close: 535 --><font class="italic">str</font><!-- open: 536, close: 536 --> <!-- MATCHED MATCHED MATCHED -->.  It must be a string,
and precedes any arguments processed by the iteration.  As an example,
the following are equivalent:
<pre class='lisp'>
(apply (function format) (list* stream string args))
(format stream "~1{~:}" string args)
</pre>
This will use <!-- open: 537, close: 536 --><font class="lisp">string</font><!-- open: 537, close: 537 --> <!-- MATCHED MATCHED MATCHED --> as a formatting string.  The <!-- open: 538, close: 537 --><font class="lisp">~1{</font><!-- open: 538, close: 538 --> <!-- MATCHED MATCHED MATCHED --> says it will
be processed at most once, and the <!-- open: 539, close: 538 --><font class="lisp">~:}</font><!-- open: 539, close: 539 --> <!-- MATCHED MATCHED MATCHED --> says it will be processed at least once.
Therefore it is processed exactly once, using <!-- open: 540, close: 539 --><font class="lisp">args</font><!-- open: 540, close: 540 --> <!-- MATCHED MATCHED MATCHED --> as the arguments.
As another example, the <!-- open: 541, close: 540 --><font class="lisp">format</font><!-- open: 541, close: 541 --> <!-- MATCHED MATCHED MATCHED --> function itself uses <!-- open: 542, close: 541 --><font class="lisp">format-error</font><!-- open: 542, close: 542 --> <!-- MATCHED MATCHED MATCHED -->
(a routine internal to the <!-- open: 543, close: 542 --><font class="lisp">format</font><!-- open: 543, close: 543 --> <!-- MATCHED MATCHED MATCHED --> package) to signal
error messages, which in turn uses <!-- open: 544, close: 543 --><font class="lisp">ferror</font><!-- open: 544, close: 544 --> <!-- MATCHED MATCHED MATCHED -->, which uses <!-- open: 545, close: 544 --><font class="lisp">format</font><!-- open: 545, close: 545 --> <!-- MATCHED MATCHED MATCHED --> recursively.  
Now <!-- open: 546, close: 545 --><font class="lisp">format-error</font><!-- open: 546, close: 546 --> <!-- MATCHED MATCHED MATCHED --> takes a string and arguments, just like <!-- open: 547, close: 546 --><font class="lisp">format</font><!-- open: 547, close: 547 --> <!-- MATCHED MATCHED MATCHED -->,
but also prints some addtitional information: if the control string in <!-- open: 548, close: 547 --><font class="lisp">ctl-string</font><!-- open: 548, close: 548 --> <!-- MATCHED MATCHED MATCHED -->
actually is a string (it might be a list -- see below), then it prints the string
and a little arrow showing where in the processing of the control string the
error occurred.  The variable <!-- open: 549, close: 548 --><font class="lisp">ctl-index</font><!-- open: 549, close: 549 --> <!-- MATCHED MATCHED MATCHED --> points one character after the place of
the error.
<pre class='lisp'>
(DEFUN FORMAT-ERROR (STRING &amp;REST ARGS)
       (COND ((STRINGP CTL-STRING)
	      (FERROR NIL "~1{~:}~%~VT<u><font color='green'>SAIL</font></u>~%~3X/"~A/"~%"
		      STRING ARGS (+ CTL-INDEX 3) CTL-STRING))
	     (T (FERROR NIL "~1{~:}" STRING ARGS))))
</pre>
This first processes the given string and arguments using <!-- open: 550, close: 549 --><font class="lisp">~1{~:}</font><!-- open: 550, close: 550 --> <!-- MATCHED MATCHED MATCHED -->, then
tabs a variable amount for printing the down-arrow, then prints the control
string between double-quotes.  The effect is something like this:
<pre class='lisp'>
(format t "The item is a ~[Foo~;Bar~;Loser~]." 'quux)
&gt;&gt;ERROR: The argument to the FORMAT "~[" command must be a number
                   <u><font color='green'>SAIL</font></u>
   "The item is a ~[Foo~;Bar~;Loser~]."
<u><font color='green'>SAIL</font></u>...
</pre>

<tr valign='top'>
<td><font class='lisp'> ~}</font></td><td>Terminates a <!-- open: 551, close: 550 --><font class="lisp">~{</font><!-- open: 551, close: 551 --> <!-- MATCHED MATCHED MATCHED -->.  It is undefined elsewhere.
</td></tr><!-- item_ --></table><!-- end table -->


<tr valign='top'>
<td><font class='lisp'> ~^</font></td><td>This is an escape construct.  If there are no more arguments remaining
to be processed, then the immediately enclosing <!-- open: 552, close: 551 --><font class="lisp">~{</font><!-- open: 552, close: 552 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 553, close: 552 --><font class="lisp">~&lt;</font><!-- open: 553, close: 553 --> <!-- MATCHED MATCHED MATCHED --> construct
is terminated.  (In the latter case, the <!-- open: 554, close: 553 --><font class="lisp">~&lt; formatting <!-- open: 555, close: 553 --><font class="italic">is</font><!-- open: 555, close: 554 --> performed, but no
more clauses are processed before doing the justification.
The <!-- open: 556, close: 554 --><font class="lisp">~^</font><!-- open: 556, close: 555 --> should appear only at the <!-- open: 557, close: 555 --><font class="italic">beginning</font><!-- open: 557, close: 556 --> of a <!-- open: 558, close: 556 --><font class="lisp">~&lt;</font><!-- open: 558, close: 557 --> clause,
because it aborts the entire clause.  It may appear anywhere in a <!-- open: 559, close: 557 --><font class="lisp">~{</font><!-- open: 559, close: 558 --> construct.)
If there is no such enclosing construct, then the entire formatting operation
is terminated.

If a numeric parameter is given, then termination occurs if the parameter
is zero.  (Hence <!-- open: 560, close: 558 --><font class="lisp">~^</font><!-- open: 560, close: 559 --> is the same as <!-- open: 561, close: 559 --><font class="lisp">~#^</font><!-- open: 561, close: 560 -->.)  If two parameters are
given, termination occurs if they are equal.  If three are given, termination
occurs if the second is between the other two in ascending order.

If <!-- open: 562, close: 560 --><font class="lisp">~^</font><!-- open: 562, close: 561 --> is used within a <!-- open: 563, close: 561 --><font class="lisp">~:{</font><!-- open: 563, close: 562 --> construct, then it merely terminates
the current iteration step (because in the standard case it tests for
remaining arguments of the current step only); the next iteration step
commences immediately.  To terminate the entire iteration process,
use <!-- open: 564, close: 562 --><font class="lisp">~:^</font><!-- open: 564, close: 563 -->.

<tr valign='top'>
<td><font class='lisp'> ~&lt;</font></td><td><!-- open: 565, close: 563 --><font class="lisp">~<!-- open: 566, close: 563 --><font class="italic">mincol</font><!-- open: 566, close: 564 -->,<!-- open: 567, close: 564 --><font class="italic">colinc</font><!-- open: 567, close: 565 -->,<!-- open: 568, close: 565 --><font class="italic">minpad</font><!-- open: 568, close: 566 -->,<!-- open: 569, close: 566 --><font class="italic">padchar</font><!-- open: 569, close: 567 -->&lt;<!-- open: 570, close: 567 --><font class="italic">text</font><!-- open: 570, close: 568 -->~&gt;</font><!-- open: 570, close: 569 -->
justifies <!-- open: 571, close: 569 --><font class="italic">text</font><!-- open: 571, close: 570 --> within a field <!-- open: 572, close: 570 --><font class="italic">mincol</font><!-- open: 572, close: 571 --> wide.  <!-- open: 573, close: 571 --><font class="italic">Text</font><!-- open: 573, close: 572 -->
may be divided up into clauses with <!-- open: 574, close: 572 --><font class="lisp">~<u><font color='green'>SAIL</font></u>;</font><!-- open: 574, close: 573 -->--the
spacing is evenly divided between the text segments.
With no modifiers, the leftmost text segment is left justified in the
field, and the rightmost text segment right justified;  if there is
only one, as a special case, it is right justified.
The colon modifier causes
spacing to be introduced before the first text segment;  the atsign
modifier causes spacing to be added after the last.
<!-- open: 575, close: 573 --><font class="italic">Minpad</font><!-- open: 575, close: 574 -->, default <!-- open: 576, close: 574 --><font class="lisp">0</font><!-- open: 576, close: 575 -->, is the minimum number of <!-- open: 577, close: 575 --><font class="italic">padchar</font><!-- open: 577, close: 576 -->
(default space) padding characters to be output between each segment.
If the total width needed to satisfy these constraints is greater
than <!-- open: 578, close: 576 --><font class="italic">mincol</font><!-- open: 578, close: 577 -->, then <!-- open: 579, close: 577 --><font class="italic">mincol</font><!-- open: 579, close: 578 --> is adjusted upwards in
<!-- open: 580, close: 578 --><font class="italic">colinc</font><!-- open: 580, close: 579 --> increments.  <!-- open: 581, close: 579 --><font class="italic">Colinc</font><!-- open: 581, close: 580 --> defaults to <!-- open: 582, close: 580 --><font class="italic">1</font><!-- open: 582, close: 581 -->.
<pre class='lisp'>
(format nil "~10&lt;foo~;bar~&gt;")    =&gt;  "foo    bar"
(format nil "~10:&lt;foo~;bar~&gt;")   =&gt;  "  foo  bar"
(format nil "~10:@&lt;foo~;bar~&gt;")  =&gt;  "  foo bar "
(format nil "~10&lt;foobar~&gt;")      =&gt;  "    foobar"
(format nil "$~10,,'*&lt;~3f~&gt;" 2.59023)  =&gt;  "$******2.59"
</pre>

If <!-- open: 583, close: 581 --><font class="lisp">~^</font><!-- open: 583, close: 582 --> is used within a <!-- open: 584, close: 582 --><font class="lisp">~&lt;</font><!-- open: 584, close: 583 --> construct, then only the clauses
which were completely processed are used.  For example:
<pre class='lisp'>
(format nil "~15&lt;~S~;~^~S~;~^~S~&gt;" 'foo)            =&gt;  "            FOO"
(format nil "~15&lt;~S~;~^~S~;~^~S~&gt;" 'foo 'bar)       =&gt;  "BAR         FOO"
(format nil "~15&lt;~S~;~^~S~;~^~S~&gt;" 'foo 'bar 'baz)  =&gt;  "FOO   BAR   BAZ"
</pre>

If the first clause of a <!-- open: 585, close: 583 --><font class="lisp">~&lt;</font><!-- open: 585, close: 584 --> is terminated with <!-- open: 586, close: 584 --><font class="lisp">~:;</font><!-- open: 586, close: 585 --> instead of <!-- open: 587, close: 585 --><font class="lisp">~;</font><!-- open: 587, close: 586 -->,
then it is used in a special way.  All of the clauses are processed
(subject to <!-- open: 588, close: 586 --><font class="lisp">~^</font><!-- open: 588, close: 587 -->, of course), but the first one is omitted in
performing the spacing and padding.  When the padded result has been
determined, then if it will fit on the current line of output, it is output,
and the text for the first clause is discarded.  If, however, the padded text
will not fit on the current line, then a newline is output, then the
text for the first clause, then the padded text.  The first clause is
always processed, and so any arguments it refers to will be used;
the decision is whether to use the resulting piece of text, not whether to
process the first clause.  If the <!-- open: 589, close: 587 --><font class="lisp">~:;</font><!-- open: 589, close: 588 --> has a numeric parameter <!-- open: 590, close: 588 --><font class="italic">n</font><!-- open: 590, close: 589 -->, then
the padded text must fit on the current line with <!-- open: 591, close: 589 --><font class="italic">n</font><!-- open: 591, close: 590 --> character positions to spare
to avoid outputting the newline.
For example, the control string <!-- open: 592, close: 590 --><font class="lisp">"~%;; ~{~&lt;;; ~:1; ~S~&gt;~^,~}.~%"</font><!-- open: 592, close: 591 --> can be used to
print a list of items separated by commas, without breaking items over line boundaries,
and beginning each line with "<!-- open: 593, close: 591 --><font class="lisp">;; </font><!-- open: 593, close: 592 -->".  The argument 1 in <!-- open: 594, close: 592 --><font class="lisp">~:1;</font><!-- open: 594, close: 593 --> accounts
for the width of the comma which will follow the justified item if it is not the last
element in the list.  If <!-- open: 595, close: 593 --><font class="lisp">~:;</font><!-- open: 595, close: 594 --> has a second numeric parameter <!-- open: 596, close: 594 --><font class="italic">m</font><!-- open: 596, close: 595 -->,
then <!-- open: 597, close: 595 --><font class="italic">m</font><!-- open: 597, close: 596 --> is used as the width of the line, thus overriding the natural line
width of the output stream.  To make the preceding example use a line width of 50,
one would write <!-- open: 598, close: 596 --><font class="lisp">"~%;; ~{~&lt;;; ~:1,30; ~S~&gt;~^,~}.~%"</font><!-- open: 598, close: 597 -->.

<tr valign='top'>
<td><font class='lisp'> ~&gt;</font></td><td>Terminates a <!-- open: 599, close: 597 --><font class="lisp">~&lt;</font><!-- open: 599, close: 598 -->.  It is undefined elsewhere.
</td></tr><!-- item_ --></table><!-- end table -->


In place of a numeric parameter to a directive, you can put the letter
V, which takes an argument from <!-- open: 600, close: 598 --><font class="italic">args</font><!-- open: 600, close: 599 --> as a parameter to the
directive.  Normally this should be a number but it doesn't really have
to be.  This feature allows variable column-widths and the like.  Also,
you can use the character # in place of a parameter; it represents the
number of arguments remaining to be processed.  This is useful, for
example, for dealing with English conventions for printing lists:
<pre class='lisp'>
(setq foo "Items:~#[ none~; ~S~; ~S and ~S~:;~@{~#[~1; and~] ~S~^,~}~].")
(format nil foo)  =&gt;  "Items: none."
(format nil foo 'foo)  =&gt;  "Items: FOO."
(format nil foo 'foo 'bar)  =&gt;  "Items: FOO and BAR."
(format nil foo 'foo 'bar 'baz)  =&gt;  "Items: FOO, BAR, and BAZ."
(format nil foo 'foo 'bar 'baz 'quux)  =&gt;  "Items: FOO, BAR, BAZ, and QUUX."
</pre>


	The user can define his own directives.  How to do this is not documented
here; read the code.  Names of user-defined directives longer than one character
may be used if they are enclosed in backslashes (e.g. <!-- open: 601, close: 599 --><font class="lisp">~4,3\GRAPH\</font><!-- open: 601, close: 600 -->).

<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(format nil "foo") =&gt; "foo"
(setq x 5)
(format nil "The answer is ~D." x) =&gt; "The answer is 5."
(format nil "The answer is ~3D." x) =&gt; "The answer is   5."
(setq y "elephant")
(format nil "Look at the ~A!" y) =&gt; "Look at the elephant!"
(format nil "The character ~:@C is strange." 1003)
      =&gt; "The character Meta-<u><font color='green'>SAIL</font></u> (Top-X) is strange."
(setq n 3)
(format nil "~D item~P found." n n) =&gt; "3 items found."
(format nil "~R dog~:[s are~; is~] here." n (= n 1))
      =&gt; "three dogs are here."
(format nil "~R dog~[~1; is~:;s are~] here." n)
      =&gt; "three dogs are here."
(format nil "Here ~[~1;is~:;are~] ~:*~R pupp~:P." n)
      =&gt; "Here are three puppies."
</pre>

<!-- open: 602, close: 600 --><font class="lisp">format</font><!-- open: 602, close: 601 --> also allows <!-- open: 603, close: 601 --><font class="italic">control-string</font><!-- open: 603, close: 602 --> to be a list of strings
and lists, which is processed from left to right.  Strings are interpreted
as in the simple case.  Lists are taken as extended directives; the first
element is the directive letter, and the remaining elements are the numeric
parameters to the directive.  If the
car of a list is not a recognized directive, the list is simply evaluated
as a form; anything it writes to the <!-- open: 604, close: 602 --><font class="lisp">standard-output</font><!-- open: 604, close: 603 --> stream will
appear in the result of <!-- open: 605, close: 603 --><font class="lisp">format</font><!-- open: 605, close: 604 -->.
</div>

<div class='defun' id='format:print-list'>
  <font class='exdent'>
    <font class='funcname'>format:print-list </font>
    <font class='italic' color='purple'>destination element-format list &optional separator start-line options</font>
  </font><br>
This function provides a simpler interface for the specific
purpose of printing comma-separated lists with no list element
split across two lines.  <!-- open: 606, close: 604 --><font class="italic">destination</font><!-- open: 606, close: 605 --> tells where to send the output;
it can be <!-- open: 607, close: 605 --><font class="lisp">t</font><!-- open: 607, close: 606 -->, <!-- open: 608, close: 606 --><font class="lisp">nil</font><!-- open: 608, close: 607 -->, or a stream, as with <!-- open: 609, close: 607 --><font class="lisp">format</font><!-- open: 609, close: 608 -->.
<!-- open: 610, close: 608 --><font class="italic">element-format</font><!-- open: 610, close: 609 --> is a format-control-string which tells how
to print each element of <!-- open: 611, close: 609 --><font class="italic">list</font><!-- open: 611, close: 610 -->; it is used as the body of a <!-- open: 612, close: 610 --><font class="lisp">"~{...~}"</font><!-- open: 612, close: 611 --> construct.
<!-- open: 613, close: 611 --><font class="italic">separator</font><!-- open: 613, close: 612 -->, which defaults to <!-- open: 614, close: 612 --><font class="lisp">",<u><font color='green'>SAIL</font></u> "</font><!-- open: 614, close: 613 --> (comma, space) is a string which goes after
each element except the last.  Format-control commands are not recommended in <!-- open: 615, close: 613 --><font class="italic">separator</font><!-- open: 615, close: 614 -->.
<!-- open: 616, close: 614 --><font class="italic">start-line</font><!-- open: 616, close: 615 -->, which defaults to three spaces, is a format-control-string which
is used as a prefix at the beginning of each line of output, except the first.
Format-control commands are allowed in <!-- open: 617, close: 615 --><font class="italic">separator</font><!-- open: 617, close: 616 -->, but they should not swallow
arguments from <!-- open: 618, close: 616 --><font class="italic">list</font><!-- open: 618, close: 617 -->.  <!-- open: 619, close: 617 --><font class="italic">options</font><!-- open: 619, close: 618 --> is a string inserted before the opening <!-- open: 620, close: 618 --><font class="lisp">"{"</font><!-- open: 620, close: 619 -->;
it defaults to the null string, but allows you to insert colon and/or atsign.
</div> 

For formatting Lisp code (as opposed to text and tables), there is
the Grind package.  See <font color='red'>LINK:(</font>grind).
<!-- eof -->
</body>
</html>

